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I. User Guide 
1. Introduction 



1.1. Introduction & Legal Stuff 

Tlie part of this maniml is a general introduction to DrawTools. It isn't a tutorial on computer graphics, although 
some basic topics are discussed, For more in depth information on specific tools, consult the reference section. 

We'd love to hear from you. If you have any questions, comments, or complaints, please feel free to write to 
Pegasoft at: 

Pegasoft 

Honsberger Avenue, R. R, ft\ 
Jordan Station, Ontario, Canada 
LOR ISO 

This manual and the related software contained on the diskettes are copyrighted materials. All rights reserved. Duplication 
of any of the above described materials, for other than personal use of the purchaser, without express written permission of 
Pegasoft of Canada is a violation of the copyright law of the United States and Canada, and is subject to both civil and 
criminal prosecution. 

Pegasoft and DrawTools are trademarks of Pegasoft of Canada. 

1.2. What is DrawTools? 

Welcome to DrawTools, a collection of over 100 usefiil graphics and animation tools for the IIGS. The first version 
was released as shareware around the fall of 1990. Since then, it has significantly grown, with new features and 
more versatility. 

Feel free to distribute the TOOL098 file with any programs you make, but if you wish to distribute any other 
files on the DrawTools disks, please get prior permission from Pegasoft, 

1.3. System Requirements 

DrawTools 3.1 requires the following: 

An Apple IIGS with system software 5.0.2 and at least 9K free RAM in bank 0. 
To use DrawTools, the following toolsets must be active: Tool Locator, Misc. Tools, Memory Manager, 
QuickDraw II, 

1.4. Installation 

1 . Copy the TOOL098 file to the Tools folder of your startup disk. (This is DrawTools,) 

2. Copy the DT.Drivers folder (the folder and its contents) to the System:Tools folder of your startup disk. 

3. Copy the icon file to your Icons folder. 

The DrawTools disks also contain the following: 

a. PicEd 3.0, a simple editor for picture libraries 

b. Lib.Converter 1.2, a utility which franslates a screen template into a picture library. The folder 
includes some sample templates. 

c. Demo. Game, a small assembly language game that demonstrate some of the animation tools 
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d. Demo. S y s 1 6, a demo program written in Micol Advanced Basic 4.2 

e. sample programs for a wide variety of computer languages 

1.5. Using DrawTools with ... 

Compiete/TML Pascal II - an interface file written in TML Pa.scal If is included on the disic in the TML.Pascal 
folder. Copy the object file to the folder containing the interface files for the other toolsets, include DrawTiwI.s in 
your USES list at the beginning of your program, 

Micol Advanced BASIC - You need to use the TOOLBOX command, A set of aliases are supplied for users with 
the latest version of BASIC: you can copy these into yoiu" program or you can use the INCLUDE conunand. Each 
alias requires a space after the tool name. 

TTi Dravs'Shadow will not work unless you are ninning a stand-alone application. There are also some tools 
I that require a Pascal string (not a BASIC string): a length (byte) followed by the text of the string, You 

cannot u.se these tools directly: you will either have to construct a string with POKEs, or u.se Micol Macro. 

All the toolsets that DrawTools requires are started for you when you use HGR or HGR2. 

Merlin 16+ - a macro file (Draw.Macs.S) is included on the disk. Copy it into your MACRO.LIBRARY 
subdirectory, and USE it in your soiirce files. 

ORCA/Pascal - an interface file (E>rawtools.int) is included on the disk. Copy this file into OrcaPascalDefs. In 
your program, include DrawTools in yoiu" USES list, 

ORCA/M - A macro file (ml6.DrawTools) is included on the disk. Copy this file into your ainclude folder. Use it 
like any other macro file. 

QRCA/C - Tliere are no interface files available: you can use DrawTools if you use the necessary tool definitions. 




DrawTools will not work with Prizm. 



Pe gasus Pascal - Follow the ORCA/Pascal directions. 
Example: Starting DrawTools 3.1, 

Pegasus Pascal: Start it like any other toolset 

Uses Conroco, , . . , DraWltoolB 
I efcart required tcwXs, or use StartGraphics 
loadOneTool 98, 

DPHandle = NewHandle(256, MylD, $C005, 0) 
DP = ord( DPHandle" ) 
Draws tar tup DP, MylD 
EKtandBuf f era 

ORCA/Pascal: Start it like any other toolset. 

Uses Coitmon, , . . , Dravfltoolsj 
( efcart required tools, or use StartGraphics } 

loadOn^oolOa, 0); { Load DraWTools } 

DPHandle i= Nev4Iandle(256, MylD, $COOS, 0) ; { allocate direct page space 3 

DP 1= ord( DPHandle' ); { convert to an integer } 

Draw!J;-.finrtUp( DP, MylD ); f start Drawroola ) 

Exb«&aau££«r0) { if using a lot of pixies ) 



i Load DrawTools 

) allocate direct page space 

j convert to an integer 

I start DrawTools 

I if using a lot of pixies 
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BASIC : Use the following commands: 

REM Start required toolB, or use HGR/HGR2. 

TOOLBOX {1, IS I 98, 0) s REM Tool Locator's LoadOn^ool 

DrawTcois_Handle = 256 s REM Allocate direct page space 

DrawTools_Adc3re8B = 

POKE 202, 1 

Get_Mem{ Drawrools_Handle, Drawrool8_AddresB) 

Address% == IHT(DrawToolB_Addreas) t REM Convert to an integer 

MyID% = Peek(238) + Peek(239) * 256 

TOOLBOX( "DrawBtarttTp i AddreBB%, MyID%) 

REM Without aliaeess TOOLBOXC 98, 2 i Address%, MylD% ) 

TOOLBOX( -ExtendBuf f are ) i REM If using a lot of pixies 

Merlin 16+: Start it like any other toolset 

USE 4! Draw. Macs 

-LoadOneTool #99}JfO 

"NevrfJandle #$100;MyID;#$C005;#0 

PLA 

PushVtord MylD 
_DrawS tartUp 

_Ext»ndBu££ers . if using a lot of pixies 

ORCA/M: Start it like any other toolset. 

MOOPY mie.DraWTools 
ph2 #98 ; load E»rawTools 
ph2 #0 

_LoadOneTool 
ph4 #0 
ph4 #$100 
ph2 Myip 
ph2 #$C0b5 
ph4 #0 
_NewH£mdle 
pha 

ph2 MylD 
_DrawStart0p 
ExbendBuf f ers 

Examples: Stopping DrawTools 3.1. 
Pegasus Pascal: 

DravShutDovu 

ORCA/Pascal: 

DravShutDown; 

BASIC: 

T00LBOX(-DrawShutDown ) 

r™ Without aliases! T00LBOXO8, 3) 

Merlin 16+: 

_DrawShutDown 

ORCA/M: 

_Dra>fShTitDowa 



) 



; if using a lot of pixies 
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2. Graphics on the IIGS 

2.1, A Brief Introduction 

Graphics is the art of drawing with a computer. In the IIGS, there is 3 special toolset dedicated to drawing called 
"QuickDraw 11", or QuickDraw for short. QuickDraw provides all the basic drawing functions for the average 
application: it draws lines, rectangles, ovals, text, cursors and many other thmgs you see on the screen. It's 
impossible to make a complete list of the QuickDraw tools here since there are well over 200; consult the Apple 
IIGS Toolbox Reference or any book introducing IIGS programming for more mforniation, 

p BASIC : Whenever you use HCOLOR, HPLOT, or the other BASIC commands, BASIC uses QuickDraw. 

Before discussing the details of DrawTools, you should know a little bit of how pictures are displayed on the 
IIGS screen. We will be discussmg 320 mode to keep things simple. The super high-resolution graphics screen is 
located in bank $E1 of memory. Each dot on the screen, or "pixel", consists of half a byte of memory , or 4 bits. 
This means up to sixteen colours can normally be displayed on the screen. The screen consists of 320 pixels 
horizontally and 200 pixels vertically. These pixels are located m the area $E12000 to $E19CFF of memory. 

The next 200 bytes, starting at $Ei9D00, are for the Scanline Control Bytes, or SCB's, one for each line on the 
screen. The SCB's determine the attributes for that line: 

bit 0...3 - the palette of the line (0 to 15) 
bit 4 - zero 

bit 5 - 1 if fill mode is active. With fill mode active, colour (usually black) behaves differently. 
If you draw an area of the screoi in colour 0, it will appear in the same colour as the area of the 
screen to the immediate left. The colour is "pulled" across the black areas of the screen, filling 
them in. 

bit 6 - 1 will cause an SCB intarupt on this line 
bit 7 - I for 640 resolution; for 320 resolution 

The memory located from $E19E00 to $E19FFF contains the 16 colour palettes (or "color tables"). Each 
palette contains 16 mteger RGB values that describe the 16 colours you can see on the screen. QuickDraw only uses 
palette (see Figure 1). Palettes and RGB colour words are discussed more below. * 



Fi gure 1 : The QuickDraw II colours (in 320 modet 
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$4DF 
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SOOF 
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lilac purple 


$DAF 
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datkgrem 


$080 


13 ($D) 


paiwmkle blue (desktop) 
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orange 


$7F0 


14 ($E) 


light grey 


$CCC 
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led 


$1X10 


15 ($F) 


white 


$FFF 



This whole section of memory, from $E12000 to $E19FFF, can be "shadowed" from $012000 to $019FFF in 
bank 1 . This area is called the shadow screen. You can use the shadow screen if you set bit 15 in the Master SCB 
when you start QuickDraw up. When the shadow screm is ui use, drawmg takes place much faster than usual. In 
addition, the shadow screen can be made invisible (with DrawTools ShadowOff) so that QuickDraw & DrawTools 
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draw many times faster than without shadowing, but the pictures will remain hidden until use DrawTools' 
QuickWipe, 



2.2 Working with Colour 

On the IIGS, the super hires screen can display 16 colours at a time with a single palette. You can change the 
current drawing colour using QuickDraw's SetSoiidPenPat(c) or BASIC'S HCOLOR=c. The hue and brightness of 
each colour is described by an RGB colour word, a combination of red, green and blue components. Each 
component can be in a range from to 15. For example, black is 0,0,0; white is 15,15,15; bright red is 15,0,0; 
orange is 15,7,0. 

DrawTools has a tool called Set Co lour that will take the red, green and blue components and give you the 
corresponding RGB value. 

Example : Creating the colour "orange" with SetColour. 

Pascal: ROBColour i= SetColour (15, 7, 0); 

BASIC: TOOLBOX( -aetColour 1 0, 15, 7, 0; RGBColour% ) 

REM Include at start for RGBColour%l Add one for each result value. 

Example : You can use QuickDraw's SetColorEntry to change a default colour: 
Pascal: SetColorEntry( 0, 5, SefcColour( 15, 7, ) ); 
BASIC: T00riB0X( -aetColour i 0, 15, 7, 0; RGBColour% } 
TOOLBOX{ 4, 16 1 0, 0, RGBColour% ) 

Besides SetColour, there is a SetColPercent will do the same thing, accept you use percentages (0...100) of 
red, green and blue components instead of values from 0...15. FadeColour will make an RGB value darker or 
brighter. BlendColour will blend to colours together to make a new colour. FindColour will find the cio.sest 
colour in a palette to the colom- word you specify. 

Although QuickDraw uses one palette, the IIGS can actually display colours from 16 different palettes at one 
time. Each line must have only one palette. DrawTools has a tool called SetPalette that will change the palette 
for a set of lines. 

i 

Example: Changing the top half of the screen (lines 0...99) to palette 1. 

Pascal; S«fcPa.lebta( 0, 99, 1); 
BASIC: TOOLBOX (-Set Palette i 0, 99, l) 

Now anything you draw on the top half of the screen will appear in the colours of palette 1 instead of palette 0. 
You can set the colours of any of the palettes using SetColorEntry( palette, colour, RGBvalue); or in BASIC, 
TOOLBOX( 4, 16: palette%, colour%, RGBvalue% ). 

FadePal will make make all the colours in a palette darker. Unf'adePal will make all the colours in a palette 
brighter. A more powerfiil version of FindColour is FindPalette Give FindPalette a palette of colours, and it 
will try to match them up to colours in the current palette. This tool is usefiil for NDAs: you can never be sure 
which colours are on the screen if an NDA is running under a paint program. FindPalette can tell you if the colours 
have changed, and to what. 

Example: See the reference for more details. If you want to find the closest colours on the screen to the standard 320 
palette: 

Defme the colours array:0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
Define the Palette:$000, $777, $841, $720, $78F, $CCC, $FFF 

After the call is made, the values in colour list will change to reflect the actual numbers for these colours on the 
current screen (or the closest colours them). 
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2.3 Fades, Wipes, and Dissolves 

What set of tools would [)e complete without some way to gracefully change from one scene to another? Tliere 
are four basic ways to make such a traiisition. The simplest way is to erase the screen and draw a new picture; it's 
easy, effective, but it lacks a certain class, especially on a computer with the possiblities of the IIGS. A common 
way to switch pictures is with a fade, A fade changes all the colours to a single colour, and then reverses the process 
to reveal a new picture. While the colours are identical, any drawing you do is invisible. DrawTools provides two 
fades: (1) QuickFade, the standard fade used in so many applications, which dims all the colours in the first eight 
palettes to black; (2) IncrFade, which fades out everything except the red component, and then fades to black 

A second method of switching pictures is with a wipe. A wipe copies a picture firom shadow screen onto the 
screen in a special order. DrawTools provides two wipes which copy the shadow screen to the main screen: (1) 
Quick Wi pe, which instantly copies one to the other, and (2) VB Wipe which copies using a Vencian blind effect. 

The last way to change screens is a dissolve. This is a special kind of wipe which operates on a pixei-by-pixei 
basis. There are no dissolves in DrawTools. 

Example : How to fade to black, draw something new, and imfade to reveal it. 

Pascal: 

QulokFadeOut (1) ; 
repeat until FadsDoua; 

{draw the new screen here} 
QuioJeFadeln(l) ; 

repeat until FadaDone; 

BASIC: 

TOOIiBOX(~QuiofcFad«Out : 1) 

REPEAT 

TO0Ii80X(''FadeDon» t 0; FadeDone%) 
UNTIIj FadeDone% <> 
SSM Draw the new screen here 
TOOLBOXC-QuiokFadaln i 1) 

REPEAT 

'rOOLBOX{''FadeDone i 0; FadeDone%) 
UHTIL FadeDone% <> 

Merlin 16+: 

~QuiokFadeOut #1 
QFOLoop -Fad«Don« 
PLA 

BEQ QPOLoc^ 
* Draw new screen here 

-QuiokFadaln #1 
QFILoop -FadaDona 

PLA 

BEQ QFILoop 

Example : How to use the Venician Blind wipe tool to wipe a new screen over an old one. 

Pascal; 

(make sure the shadow screen is allocated) 
DrawSbadov; 
SbadowOf f ; 

[draw the new screen here) 
VBWlpa; 



f 



1 
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DrawHain; { or ShadowOn, if you want to uee the shadow screen ) 
B A S IC : Reminder: Uses the shadow screen: stand-alone programs only! 

TOOLBOX(~DrawShadow ) 
TOOLBOX ( -Sh ado wOff ) 
REM Draw new screen here 
TOOLBOX {~VBHipe ) 
TOOLBOX ("DrawMain ) 

Merlin 16+ 

_DrawSbadow 
_8hadowOf f 

;draw the new ecreen here 
VBHip* 
DrawHain 



1 
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3. Animation 



3.1 What is Animation? 

Animation is ttie illusion of motion created when a sequence of pictures is rapidly displayed. Each picture, 
called a cell or frame, is a modified version of the picture before it. When each of these still frames is displayed 
quickly, one after another, they give the illusion of smooth motion. A movie displays 24 frames per second, and at 
60 or beyond the eye can't distinguish animation from real motion. Reasonable computer animation can be achieved 
at speeds of even 4 frames per second, 

To show a flag being raised, you would first start with a picture of flag pole. Then you would create a series of 
picttires, each with the flag a little farther up the pole. The final picture would be drawn with the flag at the top of 
the pole. Each of these pictures of the flag and the flag pole is a frame. Wh^i you display these pictures rapidly and 
in order, the flag appears to smoothly rise up the pole, This is the fundamental principle of animation, 

3.2 Animation Examples: Dialog Ideas 

To view some sample animation sequences, start KcEd and load the dialog.pics picture library included in the 
PicEd folder. This file is an unpacked picture library created from the Dlog.Ideas320 file using the Library Converter 
utility. Once the file is loaded, try some of the following animation sequences. 



Name Sequence Speed 

1. Note Alert 0,1,2,3,3,3,255,0 4 

2. Caution Alert 4,5,6,7,6,5,255,0 2 

3. Stop Alert 8,9,10,11,255,0 3 

4. Working GS 12,13,14,12,13,14,12,13,14,15,15,15,255,0 5 

5. Swap Disks 16,17,18,19,20,21,22,23,255,0 2 



To try one of these animations: 

1 . Click on the ani button. 

2. Click on the seq hitton. , 

3. Type in the picture sequence, one number at a time, 

4. Click on the Go! button. 

5. Type in the speed number, 

6. To stop the playback, hold down the mouse button. 

Try some experiments. 

3.3 Colour Cycling 

One of the simplest methods of performing animation is colour cycling. It is the process of changing RGB 
colour words to make objects on the screen appear and disappear. Most paint programs for the IIGS have some kind 
of colour cycling feature. 

To use colow cycling, you draw only one picture, but you paint differait frames in differ^t colours. With the 
flag pole example, you could draw a series of flags up the flag pole, each in a different colour, the lowest flag in 
colour 1, the second lowest in colour 2, and so on. When you are finished, you have a flag pole full of coloured 
flags (see Figure 2), If you change all of the colours except colour 1 to black, the only flag that is visible is the one 
on the bottom of the flag pole. If you change colour 1 to black, and change colour 2 to the colour of the flag, the 
second flag on the flag pole appears. By cycling through the current palette, making one colour aftea- another visible, 
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the flag appears to rise up the pole, 



Figure 2: Flagpole Example 
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To do colour cycling in the current palette, all you need are two QuickDraw tools: GetColorEntry and 
SetColorEntry. The first gives you the RGB colour word for a particular palette entry. The second lets you change 
a colour in a specified position in a palette to a new colour. There is also a GetCoiorTable and SetColorTabie that 
lets you change whole palettes at a time. Here's an example of how you might write the flag animation: 

Example: Colour Cycling of a flag pole with five flags. 

Pascal: 

procedure AnimateFlagPole; 

var OldColoura i ColorTable; 

FlagColour, IjastFlagColour, i t integer; 

begin 

GetCoiorTable (0, OldColours) ; { save the original colours } 
lABtFlagColour t= 5;{ used to erase old flags } 

for i )= 1 to 5 do SetColorEntry <0, i, $000) > { erase all the flags } 
for i )= 1 to 100 do begin ( one hundred timee } 

for FlagColour i= 1 to 5 do begin { for each flag colour } 

SetColorEntry (0, LaetFlagColour, $000) ; { Make the last flag invisible } 
SetColorEntry CO, FlagColour, $FFF) ; ( draw the flag in white ) 
LastFlagColour i= FlagColour; { this flag gets erased next ) 
end; 

end; ' 
SetColorTabie (0, OldColoure) ; { restore original colours } 
end lAnitnatePlagPolel ; 



BASIC: 

DIM 01dColourB%ClE) 



PROC AnimatePlagEtole 

Oldcolourfilj% = AE«R( 01dColours%( ) i REM Get address of array 
OldColourflH% =PEEK{202) 

TOOLBOX ( 4, 15 i 0, 01dColoureH%, OldColoursL% ) 
La8tFlagColour% = 5 f 
FOR i% = 1 TO 5 I 

TOOLBOXC 4, 16i 0, i%, ) 
NEXT i% 

FOR i% = 1 TO 100 
FOR FlagColour % 
TOOLBOX ( 4, 
TOOLBOX( 4, 



! REM Save colours in the array 
REM Used to erase old flags 
REM Erase all the flags 



1 TO 5 

16) 0,LaetFlagColour%, 0) 
16 1 0,FlagColour%, 4095) 
Last FlagColour % = FlagColoxjr* 
NEXT FlagColour% 
NEXT i% 



RH4 One hundred times 
REM For each flag colour 
SSM Make the last flag invisible 
REM Draw the flag in white 
REM this flag gets erased next 
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TOOLBOX (4, 14 t 0, OldColour aH% , 01dColouraL%) ! REM Restore original colours 

ENDPROC 

You can do even more impressive colour cycling by changing an entire palette at a time. This is used by many 
video games to create animation across the whole screen without having to do a lot of work, For example, the 
pixels for water inay never be redrawn. Wafer looks like it's moving because the colours of the water pixels are 
slowly changing. Tliis is an impressive animation effect that take very little effort on the part of a program. 

DrawTools provides two tools for palettes that work like GetColorEntry and SetColorEntry, GetPaiette gives 
you the palette being used for a particular line on the screen. SetPalette, which we have seen before, lets you change 
the current palette over a range of lines. 

Example ; Palette Cycling. 

Pascal: 

procedure CyclePalettes) 

var OldPalette, Palt^um, Delay, i i integer; 

begin 

OldPalette i= a«tPalotte {1) ; { eave the original palette number ) 

for i 1 to 100 do begin! one hundred times } 

for PalNum r= to 15 do begin! change the ecreen palette } 

fletP«l«tt« (0, 199, PalNuro) ; C to each of the 16 palettes } 
for delay (=■ 1 to 5 do HaltVB/{ time delay = 1/6 second 3 

end; 
end; 

SetPalwtte {0, 199, OldPalette);! restore the original palette } 
end !CyclePalettes) ; 

BASIC: 

PROC CyclePalettes 

T00LBOX(~QetPiilette s 0, 1 ; OldPalette%) i REM eave the original palette 
FOR i% = 1 TO 100 

FOR PalNum% = TO 15 r REM change the screen palette 
TOOLBOXC-StttPaltttto lO, 199, PalNum%) 
FOR delay% = 1 TO 5 

TOOLBOX(--HaitVB )t REM time delay = 1/6 second ' 
NEXT delay% 
INEXT PalNuin% 
NEXT i% 

T0OLBOX{~S»tPBl«tt« lO, 199, OldPalette%) i REM restore the original palette 

ESSIDPROC 



3.4 The Art of Animation: Draw, Erase and Redraw 

Colour cycling is fine for some kinds of animation, but a program often needs to save many of the colours in 
the palette for other uses. The more conventional approach to animation is to draw an object on the screen, erase it, 
and then draw it again somewhere else. This cycle of draw, erase, draw, erase, is the technique used in most 
computer games. 

The one problem with draw/erase/redraw animation is flicker. This occurs when the object being animated can't 
be redrawn fast enough. The eye sees the picture wlien it's there and when it isn't there, and this makes the object 
you're animating appear to flicker. One of the easiest ways of reducing flicker is to use DrawTools' Wait VB tool 
before you try to erase anything. 

Exapipliei: The following procedure moves a white box across the screen by drawing it, erasing it, and then redrawing 
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it. WaitVB is used to keep the flicker low. To see the box flicker, try replacing the WaitVB loop with "for delay := 
1 to 5000 do and change the number of iterations. 

Pascal; 

procedure MoveABoxj 

var Box ( recti ir delay i integer; 

begin 

SetRect( Box, 0, 10, 30, 40) / C the 30 x 30 box } 
SetSoXidPenPat { 15 ) ; { the box colour } 
SetSolidBackPat ( ) j { the erasing colour } 
for i := 1 to 20 do begin ( 20 times } 

OffeetReotC Box, 10, 0) ; { move the box 10 pixels to the right } 

PaintRect ( Box ) ; { draw it i 

for delay t= 1 to 5 do HnitVB; {time delay -= 1/6 aeccnd ) 

C we just finished a WaitVB I } 
EraseReot { Box ) ; ( erase the box without flicker } 
end; 

end; 

BASIC: 

DIM Box%(8) I R£M Space for a rectangle 
PROC MoveABox 

REM I'm assuming BoxH% & BoxL% ie the address of the box% array. 

T0OLB0X( 4, 74 t BoxH%, BoxL%, 0, 10, 30, 40} i REM create a 30 x 30 box 
HOOIjOR = 15 
BiCCODOR = 

FOR i% = i TO 20 I RH4 20 times 

T00IjB0X(4, 75 I BoxH%, BoxL*, 10, 0) ! REM move the box 10 pixels to the right 
TOOLBOX (4, 84 i BoxH%, BoxL%) t RSd draw it 
FOR delay% = 1 TO 5 

TOOLBOX {-HaltVB ) ( REM time delay = 1/6 eeccnd 
MEXT delaY% . 

TOOLBOX (4, 85 i BoxHft, BoxL% )t RM erase the box without flicker i 
E!^ i% 

EKDPROC 

3.5 Bit-Mapped Pictures 

Each time QwickDraw paints an object on the screen (like our box) it has to do a number of things: 

a) Make sure the mouse arrow isn't erased. 

b) Make sure the object is actually on the screen. 

c) Make sure the object is within the clipping & visible regions of the current window or grafiXMl. 

d) Calculate which colours to use with the pen pattern and pen mask. 

e) Compute which pixels to change in the current pen mode & size. 

Ail this is what makes QuickDraw so handy and powerfxil, but it also makes it slow, too slow except for the 
simplest kinds of animation. After all, if we are drawing a space ship, we don't need specuii pen modes, sizes, 
patterns and the rest of those features. To draw a picture very quickly, DrawTools provides a sp«:i;d set of tools call 
the drawing tools. There are 8 drawing tools: Draw, Draw48, DrawAt, Draw48At, Dra%v<)n, Drftw480n, 
DrawOnAt and Draw480nAt. The basic tool, Draw, draws a bit-mapped picture library picture (24 pixels wide 
and 24 pixels high, the ones used with PicEd and the Library Convaier). TTie other tools are variations on Draw: 
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the "48" tools draw 4 pictures at once (like you see in the doiible-sizetf window in PicEd); the "At" tools let you 
specify the screen position to draw at; and the "On" tools let you draw matted pictures. We'll talk more alwut 
pictures and mattes later. Because each of these tools is customised for a particular size and "pen mode", they draw 
pictures many times fa.ster than QuickDraw can. 

Before we can use the drawing tools, we need to load a pictuire library from a disk with the LoadLibrary tool. 
A picture library is a .set of 32 bit-mapped pictures created with PicEd or the Library Converter utility. LoadLibrary 
loads pichire library from a disk and it gives you an "ID code" tliat you can use later on to refer to the library. 
LoadLibrary has some special parameters that will be described later on when we talk about matting. There is also 
an UnloadLlbrary tool, but you normally don't need to use it. 

You can only draw with one library at a time. To specify which library we want to draw with, we need to use 
the SetLibrary tool, There is also a GetLibrary tool that returns the ID co<le for the ciurent library. 

"qI LoadLibrary uses a GS/OS struig for the pathname: there is no direct way in BASIC to use GS/OS strings. 



We can fake the LoadLibrary/SetLibrary calls with BLOAD. This only works with unpacked libraries. 



REM Dravfl'oole_Addr% is the direct page space you allocated when you started DraWFoole, 
DrawToola_Buffer = PEEK(DraWroole_Addr%+4) + PEEK(DrawToolB_Mdr%+5) * 256 
POKE 202,0 ( REM In BASIC 5,0, we what to load the whole library 
BLOAD "path name of picture library", DraWroolB_Buf f er, 9216 

Example : The following procedure demonstrates how to load and display the pictures in an (unpacked) library. The 
LoadLibrary tool requires a GS/OS string (a two-byte length followed by the string itself), so refer to your particular 
language on how to define a GS/OS sfring. 

Pascal: 

procedure DumpOut Library ( pathname t GSOSString) ; 

var TheLibrary i integer) { ID code for the library ) 

begin 

TheLibrary i= Lo«dIilbr«ry ( pathname, 0, 0) j { load the library frcm disk 3 
S*tLibrary( TheLibrary );{ use this library to draw with } 
for y 1= to 3 do { 4 rows } 



PROC DumpOutlAbrary 

REM Fake the LoadLibrary/SetLibrary as described above (or use Mi col Macro & LINK) . 
FOR y% = TO 3 I REM 4 rows 



FOR x% = TO 7 t REM 8 pictures per row 
ScreenX% = x% * 32 
ScreenY% = y% * 32 
PicNum% = x% + y% * 8 

TOOLBOX C-DrawAt t ScreenX%, ScreenY%, PicNuin% ) 

IffiXT y% 




Example : Loading a library in BASIC without LoadLibrary or SetLibrary. 
BASIC: 



for X i= to 7 do C a pictures per row } 

Dr«wAt( X * 32, y * 32, x + y * 8 ) ; { draw picture # x+8y } 



end; 



BASIC: 



KtTOPROC 



Example : You can animate pictures with the drawing tools in the same way that we animated the box. If you create 
a picture of a box using PicEd in pictiu* of a library, and you leave picture 1 of the library blank (to erase with), 
then you can animate this box using the following procedure. 
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Pascal: 

procedure MoveBoxInADrawToolsLibrary ( pathname : GSOSString) ; 
const Box = 0; { box is picture zero } 

Blank = 1; { blank picture is picture 1 ) 
Vcoc i, delay ! integer; BoxLib i integer; 
begin 

Boxlib >= IioadLibraryi pathname, 0, 0) ; { load the pictures J 

S«t£ilbrary( BoxLib ) ; { draw with this set ) 

for i t= 1 to 28 do begin { 28 times ) 

DravAt( i * 10, 20, Box) ; C draw a box ) 

for delay i= 1 to 5 do WaitVB; {time delay =1/6 second 1 

DravAtC i * 10, 20, Blank) ; { erase the box } 

end; 

end; 

BASIC: 

PROC MoveBoxInADrawToolBLibrary 
Box% = 
Blank% = 1 

REM Load and set the library 
FOR i% = 1 TO 28 
x% = i% * 10 

TOOLBOX C"Dr a wAt ) X%, 20, Box%) 
FOR delay% = 1 TO 5 

TOOLBOX(~W«itVB ) 
NEXT delay% 

TOOLBOX ("DraKAt ! x%, 20, Blank%) 
NEXT i% 

ENDPROC 



3.6 Caching with Library Buffers 

DrawTools provides a caching mechanism that can reduce the swapping time when you change from one library 
to another with SetLibrary, If you need the extra speed that caching provides, use the ExtendBuffers too! after 
DrawStartUp. Now each time you use SetLibrary, the library will be loaded mto a library buffer in bank 0. If you 
use SetLibrary to select a library which is already in a buffer, DrawTools will switch to the appropriate buffer 
without reloading the library from main memory. 

DrawTools can allocate up to 5 library buffers. Only the libraries you use the most will be cached; in order to 
get the best performance horn the caching mechanism, use the ResetB uffers tool when you are about to use a new 
set of libraries. This clears the old libraries from the library buffers in preparation to receive a new set of libraries, 
such as when a new level in a game is about to start. 

You can pre-load the library buffers when they are clear by usuig SetLibrary once for each library you will be 
using. 

3.7 Mattes ; Merging the Background with a Picture 

Using DrawAt, we can create animated objects that move about the screen by drawing, erasing, and redrawing. 
But these tools destroy anything they are drawn on. For instance, if the screen contains a picture of a tree, and we 
use DrawAt to place a picture of a man on top of it, we get a tree with a 24x24 rectangle in it and a man within the 
rectangle. The picture is drawn "as is" overtop of the background. What we need is a way to combuae the picture of 
the man with the tree. We want the empty pixels about the man to act as if they were transparent. 
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Matting is the process of merging a picture with what is on the screen by using a special matte, or mask, which 
indicates the portions of the picture wliich should be treated as transparent. If you have used QuickDraw II, you have 
already seen mattes used. When you create a cursor, you create a picture of the cursor and then you make a mask to 
indicate where the screen pixels show through, The pen mask works in a similar way: pixels marked as white show 
through. 



Figure 3; Merging the Background with a Picture 



Background 




Matte Mask 



Picture 



mmmm& 



Result 



DrawTools also uses mattes to merge pictures with a backgroimd, This is done with the "on" drawing tools 
(DrawOn, DrawOnAt, ...). Each of these tools requires a matte to immediately follow the picture you are trying to 
draw. Creating a matte mask is easy. In PicEd there is a button named "mask". When you click on the button, 
PicEd will create a matte for the current pictm-e and place it in the following picture position. The effect is shown in 
the window with the red background. When the mask is made, each black pixel in the original picture is assumed to 
be transparent. To view the matte, edit it. Each white pixel represents a pixel that will be taken from the 
background, and each black pixel represent a pixel that will be taken &om the proceeding pictme. It looks rather like 
a silhouette of the original picture. 

If we want to make an entire library of matted pictures, there is even an easier way to create the matte masks. 
We draw pictures in each of the even numbered library positions (0, 2, 4, .... 30). Then we can tell LoadLibrary that 
the masks are missing and that SetLibrary will have to generate all the masks in positions (1, 3, 5, 31) for us, 
The following procedure shows the pictures in this kind of library. Note that the pictures will be drawn on top of 
whatever was previously on the screen. 

Example : EXrawing the contents of a picture library with matted pictures 

Pascal: 

procedure DumFOutJilattedLibrary( pathname s GSOSStrlng) ; 

var TheLibrary i integer; { ID code for the library ) 



begin 



TheLibrary i= LoadLibrmryC pathname^ 0, $4000) ; C bit 14 = we'll need maekel j 
S*tLibrary{ Theldbreiry ) ; ( use this library to draw with } 
for y to 3 do{ 4 rows J 

for X 1= to 7 do [ picttLree per row ) 

if not odd(x) thent Skip the maBke ® 1,3,... 3 

DrawOn&b( x * 32, y * 32, x + y * 8 ) ; { draw picture # x+8y ) 



end; 



BASIC: 

PROC DumpOutMattedLibrary 
REW Load and est the library 

TOOLBOX(-'OenAllMaoke ) i REM Generate matte maeke for even -numbered pictures 
FOR y% = TO 3 

FOR x% = TO 7 STEP 2 
Screenx% = x% * 32 
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ScreenY% = y% * 32 
PicNum% = xft + y% * 8 

TOOLBOX ( "Dr a wOn At iScreenx%, Screeny%, PicNum* ) 
NEXT x% 

NEXT y% 
ENDPROC 



If we don't want every black pixel to be treated as transparent, we will have to create the masks by ourselves. 
For instance, we niay create a picture of a man with a black pixel for an eye. Create a niatte mask using the mask 
button, and then edit the matte and remove the white pixel where the eye is. Now the eye won't be treated as 
transparent, 

Now we can create pictures like we see in video games which move overtop of the backgroiind. However, 
erasing these pictures becomes a problem. We can't simply use a blank picture as we did before because the 
background isn't blank. To erase the pictures drawn with draw on, we need to replace the piece of the background 
that lay under the picture. But when we use DrawOn, we've changed the background on the screen by adding our 
DrawOn pictures. 

The answer to this dilemma is to store the background in the shadow screen. DrawSlmdow and DrawMain 
tools let you switch whenever you want between the shadow screen and the main screen, ShadowOff turns off the 
shadow screen; you can still draw to it, but what you draw remains invisible until you "wipe" it to the main screen, 
ShadowOn turns the shadow screen on so that anything you draw will be copied to the main screen and become 
visible. 



Figur ? 4: The shadow screen and animation 
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The main screen holds the 
foreground and background 



The shadow screen holds an uncorrupted copy of the 
background 



Rather than get into the details of how the shadow screen works, here's how we get around the erasing problem. 
First, we put the background into both the shadow screen and the main screen at the same time. The easiest way to 
do this is to use tJrawShadow & ShadowOn and start drawing. Second, we use DrawMain and draw our matted 
pictures. The copy of the background that is sitting in the shadow screen remains unchanged. Finally, to erase our 
matted picture, we use DrawShadow and draw empty matted pictures. Since all pixels are transparent in an empty 
matted picture, the background is copied to the main screen and erases any picture that we drew previously. If it 
soimds complicated, it is, but it's easier than trying to capture the pixels in the background each time we draw with 
matted pictures, 

Example :Tlus is the MoveABox procedure rewritten to move the box overtop of a background picture. It should 
help you put things together: 

Pascal: 

proce<iure ^JoveMattedBoxInM)rawToolsI^ibrary{ pathname i QSOSString) ; 
const Box = J { box is picture (picture 1 will be the matte mask) } 

Blank = 2; { blank picture is picture 2 (picture 3 will be the matte mask) } 
var i, delay i integer; BoxLib i integer; 
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begin 

DrawShadovr; { ranember to specify the shadow screen In ODStartup } 
ShadowOn; 

CLS{0};{ erase the shadow screen (and the main screen) } 

{ Draw sotne stuff on the screen here - this will be in the background } 

BoxLib 1= LoadLlbrary ( pathname, 0, $4000) ; { load the pictures } 

6otLibr«ry( BoxLib );C draw with this library j 

for i 1= 1 to 28 do begin { 28 times } 

DrawMaln; { switch to the main screen ) 

DrawOnAt{ 1 * 10, 20, Box) ; { draw a box 1 

for delay t= 1 to 5 do HalbVB; {time delay = i/6 second } 

DrawShadovr; { switch to the shadow scm j 

DrawOnAt( i * 10, 20, Blank) ; ( erase the box } 
end; 

end; 



3.8 Pixie Power: Automatic Animation 

Up until now we've been looking at how to draw pictures in PicEd that we can animate and move around the 
screen. You could do all the animation yourself using the drawing tools to play back pictures in a specific order and 
erase them as appropriate. Animation involves not only pictures, but arranging them into sequences and moving the 
pictures about the screen. DrawTooIs has a special data structure to help you do just that, and it's called a pixie. It's 
sort of the .software counterpart of a hardware sprite such have you may have seen on a Commodore 64. 

A pixie is an animated object that can move aroimd the screen, Pixies are very flexible. They can be matted or 
unmatted. Hiey can have a direction or stand still. They can temporarily become invisible and then reappear 
somewhere else. They can use pictures from more than one library. In the DrawTooIs' game demo, the mother ship 
and the bombs it was dropping were all pixies, 

Each pixie consists of two parts: 1) a sequence of picture numbers and pixie commands; 2) a data record 
describing the position and direction of motion. We have already seen examples of a picture sequence; we had to 
type in a picture sequence to do the animation examples that we did at the start of the animation section. The size of 
data record depends on what type of pixie you create: a simple, coarse, or fine pixie. The simple pixie is used to step 
through the picture sequence: it doesn't actually draw or move anything. Hie coarse pixie is a 24x24 bit-mapped 
picture that has a location and a direction. The fine pixie is similar to the coarse pixie, except that it can move with 
greater precision. For the rest of this section, we'll be talking about fine pixies because they are the most versatile. 
Most of what we'll discuss will more or less apply to the other two types, 

TTie data stnicture for a fine pixie data record is akeady defined for you in Pascal if you are using die DrawTooIs 
interface file supplied with your DrawTooIs disk. 



Table 5: Fine Pixie Data Record (Pascal) 

Type FinePixie = record 

XVectorLow, XPositionLow : integer; 
XVwtorHi, XPositionHi : integer; 
YVectorLow, YPositionLow : integer; 
YVectorHi, YPositionHi : integer; 
index : byte; 
status : byte; 

end; 
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Here is a description of each part of the record: 

XPosition - this is ciinent position of the fine pixie (0..320, the same as the drawing tools use). If "hi" is the x- 

coordinate, and the "low" is in fractions of a coordinate. Normally, you will want to leave the low's at zero. 

YPosition - this is the current Ime number of the pixie (0... 199) 

XVector - this is the speed of the x direction (<0 is left, >0 is right). 

Y Vector - this is the speed in the y direction (<0 is up, >0 is down). 

Index - this is the location of the next picture in the pixie sequence; set to for the first. 

Status - user-defmed vahie; we'll get to later. 

"Ol BASIC : To create a fine pixie record, use the DIM statement or GET„MEM. For example, DIM 
/ 1 MyPixie%(9); You will have to POKE the values into the record: the offsets for the different fields are listed 
in the reference. You will also need to use DIM or GET_MEM to create the sequences. 

■p] For instance, XPositionHi = iOO, XPositionLow = 0, YPositionHi = 50, YPositionLow = 0, means the 
/ I pixie is at (100, 50). If XVector and YVector are all zero, the pixie is standing still, 

A picture sequence is simply list of bytes with the picture numbers to draw. The index to the sequence is m the 
data record. 

Example : The following is an example of how to create a pixie of the swap disks animation that we saw in the first 
section. It uses SetPixie to create a new pixie. The constants dVisible and dPinePixie are in the DrawTools 
interface file and are H.sed here just to make things easier to read. SetPixieSeq lets you select the sequence of pictures 
that will make up the pixie. There are also GetPixie and GetPixieSeq tools that return to you a pointer to the data 
record or sequence for one of the pixies. 

Pascal: 

procedure Setl^Di8kSwapPixie(Dialog_Pice_Path i GSOSString) ; 
type APictxireSequence = array [0.. 9] of byte; 
var Pics t APictureSeqence; 

DiekPixie t FinePixie; 

DialogLib i integer; 
begin i 

Pics to] )= 16; { list of pictures ] 

Pica(l] 1= 17;Pic8(2] i= i8;PiGB[3] >= 19 ; { in the animation } 
Pice [4] 1= 20;PicB[5] i= 21;PicB[6] t- 22; 
Pics [7] 1= 23;Pics[8j i= 255;PicB[9] i= 0; 

DialogLib i= Lo«dI.lbr»ry (Dialog_Pics_Path, 0, 0) ; t load the dialog pice } 
g«tPi3ii«(0, dViBible+dFinePixie, ©DiekPixie) ; ( pixie visible & a fine pixie 3 
S«tPlxl«8»q(0, DialogLib, ©Pics) ; { pixie uses dialog. pics } 
( & the picture sequence } 
with DiekPixie do begin 

XPositionLow t= 0;XVectorLow i= 0; { place it at (50,50) ) 

XPositionHi i= 50;XVectorHi t= 0; E and dcsi't move aroundl J 

YPositionLow t= 0;YVectorLow i= 0; 

YPositionHi i= 50;YVectorHi := Oj 

Index 1= 0;{ the first picture ie ) 
{ the first in the array! 

end; 

end; 

Once a pixie is created, it is easy to anipiate it with the AnimatePixie tool. Animate pixie moves the pixie (if 
necessary) and then uses the drawing tools to draw the pixie. Note: it doesn't erase the pixie for you, but we don't 
have to erase anything for this pixie because it isn't matted nor is it moving around. 
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Examp le: How to animate a single non-matted fine pixie. 

Pascal: 

procedure AniniateDiskSwapPixie(Dialog_Pic8_Path i GSOSString) ; 
{ — you can fill thie in from the above example ) 

Dialogliib t= LondLibrary {Dialog_Pics_Path, 0, 0) ; { load the dialog pice } 
BetPixi«(0, dVisible+dFinePixie, ®DiskPixie) ; { use pixie #0 } 
SBtPlxi«a«q(0, Dlalogbib, spies) ; { pixie uses dialog. pics ) 
{ — Initialiee the data record in here ) 
SebLibrary( DialogLib ); 
for i 1= 1 to iOO do begin 

for delay i= 1 to 5 do Hal tVB; {time delay =1/6 second ) 

AniinatePlxi«( ) ; fanimate pixie #0} 
end; 

end; 

3.9 Pixie Commands 

A pixie sequence can contain pixie commands. A command is a special instruction for the pixie, such as to 
change the pixie's vector or to switch to a different library. We have already seen one pixie command; 255 is "end of 
sequence" command and every sequence must end with it. The number following the end of sequence command is 
the position in the sequence to loop back for the next pictiire. In our disk swapping animation, we are looping back 
to position 0, the start of the sequence in order that the sequence will keep repeating over and over again. 

There are eight command that you can use with pixies, and they are outlined as follows: 

255 - En d of Sequence (All Pixies) 

Marks the end of a sequence; it's followed by the index for the sequence to loop to, It can also be used to to jump 
forward in a sequence, 

254 - Change Library (Coaree or Fine) 

Switches to a different library; it's followed by a logical library number (The second parameter in LoadLibrary). 
253 - Change X Vector (Fine) 

Changes XVectorLow & XVectorHi; it's followed by the new low and high values, eg. 254, 0, 0, 2, changes low 
to and high to 2, 

252 - Change Y Vector (Fine) 

This works the same way as Change X Vector. 

251 - Change X & Y Vectors (Fine) 

Changes X Vector then Change Y Vector, a total of 8 new bytes plus the command byte. 

250 - Change Vector (Coarse) 

Changes the vector word for a coarse pixie, 

249 - Change X & YVectors Relative (Fine) 

This command works like 251 except that tt ADDS the new vector values to the old ones. 

For example, you have a sequence of an aeroplane and you want to make the aeroplane bounce during the 
sequence. There is no way to know the X & Y vector values, so you use 249, 0, 0, 0, 0, 0, 0, 1, 0, <picture> , 
249, 0, 0, 0, 0, 0, 0, 254, 255, <pictufe>, 249. 0, 0, 0, 0. 0, 0, 1, 0. If the aeroplane Y vector is $0100 (dropping 
one line at a time) when this sequence is used, the following will happen. The first 249 causes the aeroplane Y 
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vector to increase by 1 so the plane drops 2 lines at a time. The second 249 changes the vector by -2 to 0, The third 
changes the vector back to one (the starting value). The plane does a little vertical bounce whether its gaining 
altitude, losing altitude, or flying straight. 

248 - Change Status (Coarse or Fine) 

The status field in the data record is for your own use. It works much like the RefCon vahies in things like 
windows, 248 is followed by the byte that you want stored in statiis. For instance, if you have a sequence of 
someone jumping, you can start the sequence with a 248, I and at the peak of the jump you can use a 248, 2. Now, 
to tell whether the player is jumping up or is starting to fall, all you have to do is check status to see if there is a i 
or 2. 



Example : The following example is how to enbed speed changes right Inside of a sequence. It's a sequence of 
someone jumping, where pictures 1, 2 and 3 are to be repeat during the jump. Without the speed changes, the 
sequence would be 1,2,3,255,0. But we want a nice looking jump where the jump starts fast (reduce the Y 
coordinate by 2 each animation), slows when the peak of the jump is reached (reduce by 1), and speeds up past the 
peak (see Figure 6). Because all these speed changes are embedded in the sequence, all our program has to do is 
check the pixie position to see when the jump is over. 

Pascal: 

Seq[0] 1= 253;Seqtl] t= 0;Seqt2] t= 0;Seq[3) i= 254jSeq[4] t= 255; 
Seq[5] 1= l;Seqt63 i= 2;Seq[7] i= 3; 
Seqt8] t= l;Seq[9] t= 2;Seq[10] i= 3; 



SeqCil] 


1= 253/Seq[12] 


1= 0;Seq[13] t= 


0;Seq[i4] 


1= 25S;Seq[15] 


= 255; 


Seq[16] 


1= 1; 










Seq[17] 


1= 253;SeqEl8] 


1= 0;Seq[l9) i= 


0|Seq{20] 


1= 0;S6q[21] t= 


0; 


Seq[22] 


:= 2, 










SeqC23] 


1= 253jSeq[24] 


1= 0;SeqE25] i= 


0;Seg[26] 


1= i;Seq[27] i= 


0/ 


Seq[28l 


1= 3, 










S6<l[29] 


t= 253;Se<3t30] 


1= 0;Seq[31] t= 


0/Seq[32] 


1= 2;Seq[33] != 


0; 


Seq[34] 


1= l;Seq[35] t = 


= 2)Seq(36] (=3; 








Se<l{37] 


1= 255;SGq[38l 


1= 34 J 










BASIC: 

REM Assuming Seq^Addr is the address of the sequence 
POKE Seq_Addr+0, 2B3 

POKE Seq_Addr+l, OiPOKE SGq_Mdr+2, OtPOKE Seq_flddr+3, 254 1 POKE Seq_Addi:+4, 255 
POKE Seq_JV3dr+5, iiPOKE Seq_Addr+6, 2 1 POKE Seq_Mdr+7, 3 
POKE Seq_Addr<^8, liPOKE Seq_Addr+9, 2 1 POKE Seq_flddr+iO, 3 
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POKE SGq_Addr+il, 253 

POKE Se(3_Addr+12, OiPOKE Seq_Addi:+i3, OsPOKE SecLAddr+14, 255tPOKE Sec(_Addr+15, 255 

POKE Seg_Addr+i6, 1 

POKE Seq_Aldr+i7, 253 

FOKE Se<3_Addr+ie, OsPOKE Se<3_Addr+19 , OsPOKE Seq_A(3dr+20, OiPOKE Seq_Mdr+21, 

POKE Seq_Mdr^22, 2 

POKE Se<jJV3dl-+23, 253 

POKE Seq_Addr+24, OsPOKE Seq_Addi-+2S, OsPOKE Seq_Addr+26, Is POKE Seq_Aadr+27 , 

POKE SGq_A<3<Jr+2a, 3 

POKE Seq_Addr+29, 253 

POKE Se<3_-Addr+30, OiPOKE S6<tA3dr+3i, OiPOKE Seq_Addr+32, 2 8pOKE Seq_Addr+33, 

POKE Seq_Mdr+34, liPOKE Seq_Addr+35, SsPOKE Seq_Mdr+36, 3 

POKE Seq_Addr+37, 255sPOKE Seq_Mdr+38, 34 



Merlin 16+: 





253 ) start jump with a 


adrl 


$FFFEOOOO 


db 


2f 3f X ^2 f3 


db 


253 


adrl 


$PFFFOOOO 


db 


1 


db 


253 


adrl 


$00000000 


db 


2 


db 


253 ; Starting to fallt 


adrl 


$01000000 


db 


3 


db 


253 


adrl 


$02000000 


db 


i, 2, 3 


db 


255, 34 



new Y vector 

; (-2) move up 2 lines for each picture displayed 
display six pictures, moving up 2 lines each time 
nearing top of jump; start slowing down 
{"1) move up one line next time 
display picture, moving up one line 
we're at the top of the jump; hover for one picture 
don't move for next picture 
picture 

(+1) move down one line each picture 
picture 

fall at full speed for as long as the seq. continues 
(+2) down two lines each picture 
pictures 

end of sequence - keep repeat the last 1,2,3 



Example : Jumping with the above pixie sequence. i 

Pascal: 

DoneJumping s= false; 
repeat 

Aniin>t*Plxle ( Pixi^um ); 

if HasLandedOnSonethingC PixieRec.XVectorHi, PixleRec. YVectorHi ) then begin 

PixieRec. YVectorHi s= 0; 

Donejumping t= true; 
end; 

until DoneJumping; 

BASIC: 

DoneJuirping 1 = FALSE 
REPEAT 

T0OIiBOX("Aniin«toPixia s Pixiebfum% ) 

XVectorHi% = PEEK(Pixie_Addr+6) + PEEK ( Pixie_Addr+7 ) * 256 
YVectorHi% = PEEK(Pixie_Addr+i4) + PEEK(Pixie_Addr*-15) * 256 
IF HasLandedOnScmething i XVectorHi%, YVeotorHi% ] IHEN BEGIN 

POKE Pixie_Addr+14, s REM Y vector to 

POKE Pixie_Addr+15, 

DoneJumping! = TRUE 
ENDIF 
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UMTIIi DoneJumping t = TRUE 

3.10 Managing Multiple Pixies 

We kiiow know enough to create an animated figure that can move about the screen, even overtop of a 
background. The final topic here is animatuig multiple pixies at once, especially about how to be careful when 
erasing pixies. 

Throughout our pixie examples we've been using pixie to do our animation. DrawTools supports up to 16 
pixies at once (0 ,..15). You can select any one of these pixies for your animation. However, there may be 
occaisions when you don't care which number you use. You could make a game where new bad guys can appear at 
random. At any jwint in the game, you may not be sure of how many bad guys you have already on the screen, nor 
do you know which pixies are being used. To make things like this a little easier, DrawTools provides two tools 
called NewPixie and ClearPixie. NewPixie returns the number of the first pixie that is not being used, starting 
from 15 and working down towards 0. ClearPixie lets you free up a pixie that you aren't going to use anymore. 

If you temporarily want to suspend a pixie without usmg ClearPixie to free xip it's data record and sequence 
information, there is DisablePixie tool. When a pixie is disabled, it will not be drawn or moved, but it still 
exists and can be "started up" again by using EnablePixie. A pixie may also Ik rendered invisble by using 
HidePixie. A hidden pixie will move around the screen, but it won't be drawn. It appears agam with a 
ShowPixie call. In the demo game included on the DrawTools disk, a bomb is disabled when it hits the bottom of 
the screen and it remains disabled until the Mother Ship is ready to drop it agam. The Mother Ship is made 
invisible at one point in the game by using HidePixie. 

Using several pixies is easy with the Animate command. It works the same way as AnimatePixie, but it 
animates all the enabled pixies at once, and automatically calls SetLibrary when necessary. Animate works from 
pixie 15 down to pixie 0. If you have two matted pixies overlapping, the pixie with the lower number will be 
drawn on top of the other one. Keep this in mind if the order of drawing is important. If you want a pixie airplane 
to fly behind a pixie cloud, the cloud must have a lower pixie number. 

The most difficult aspect of working with multiple pixies is erasing. Like AnimatePixie, Animate doesn't do 
any erasing. This is for two very good reasons. First, Animate can't tell which picture is blank, or in what library 
it is in, to use for erasing. Secondly, when you are animating more than one pixie at a time and they overlap each 
other, the order of erasing is very important. Ail the pixies must be erased before they are animated since 
overlapping pixies will interfere with each other. Some pixies may not even need erasing, Such as non-matted pixies 
with wide a wide border of pixels that squashes old pixels as it moves slowly arcoss the screen (as in AniDemo), 

However, there are two tools to make erasing matted pixies easy. ErasePixie erases a matted pixie by 
copying the background on top of the pixie: this works with both coarse and fine matted pixies (that are not disabled, 
of course). 

Example: EraseAliPixies will erase all that matted pixies. The main loop of a simple arcade game would look 
something like this: 

Pascal: 

Done t= false; 
repeat 

EraeaAllPixlae; 

{ move the pixies ) 
Animate; 

until Done; 

BASIC: 

Done I = FALSE 
REPEAT 
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TOOLBOX<-EraeeAllPixias ) 

REM move the pixies 
TOOLBOX ( -An ima to ) 
UNTir. Done! = TRUE 
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4. Other Functions 

4.1 Random Number Functions 

DrawTools has tliree convenient random miinber tools. These all use QuickDraw II's Random, which returns a 
random integer, RND retiims a random integer between 1 and the another number, like BASIC'S RND function. 
Odds is a boolean fimction that is tnie the given percentage of the time. Normal RND is a special funtion that 
returns a normally distributed {bell curved) numba: between 1 and another number. 

E' I You can use SetRandSeed to set the "seed" for DrawTools' functions as well as Random. (The seed 
determines which random numbers will appear. If you set the seed to a certain the number, the random 
numbers returned by Random appear in the same order,). 

Example ; Suppose your are writing an adventure game. TTie player could find a treasure chest, and the chest may be 
booby-trapped to explode 30% of the time. If the chest doesn't explode, the player gets 10 to 15 pieces of gold. 
You could program it like this: 

Pascal ; 

if OddoC30) then 

ExplodeChest 
else 

QoldPieces >= 9 + RND {6); 

BASIC: 

T0OLBOX(-'0ado I 0, 30; Result* ) 

IF Result* <> THEN C3Q3UB ExplodeChest 

IF Result* « THEN BEGIN 

'K)OIjBOX(~'RND tO, 6 J Result*) i R£M or use BflSIC's RND 

GoldPiecsB* = 9 + Result* 
ENDIF 

Example : A player in your game could also pick up a shovel lying abandoned in a corridor, and you want the shovel 
to break after an average of 20 uses. If ShovelUses is a variable with the number of goold uses left in the player's 
shovel, you could write this: 

Pascal: ShcsvelUses 1= Norma 1HND< 40 ); 

BASIC: TOOUBOX(9 8, lOli O, 40) ShovelUaeB*) 

With NormalRND, ShovelUses will usually have a value near 20 (half way between i and 40). However, there is a 
small chance the the shovel could have as many as 40 uses (a super-shovel) or as few as 1 use (a real "lemon"), 

4.2 Reading the Joystick 

There are 3 tools for reading a joystick on your IIGS. To test the joystick buttons there are two tools; GetFire 
and StillFiring, StillFiring is the easiest to use; it is if the joystick buttons are down, and greater than if they 
are up. GetFire is only greater than when a button is first down. If a button is held down, GetFire will be until 
the button is released and pressed again, The actual number returned by these tools is a sum: button has a value 
of 1, button 1 has a value of 2, and both buttons have a value 1 + 2 = 3. 

Getjoy will determine the position of the joystick, either horizontally or vertically. GetJoy(0,0) returns the 
horizontal position: a value <0 if the joystick is held to the left, if it's m the center, or >0 if its held to the right. 



DrawTools 3.1 



24 



GetJoy(0,i) is <0 for up, for centered, and >0 for down. 
Example : Using GetFoy and StiilFiring in a game. 

Pascal: 

if OnALadder then 

VerticalDir i= Gat Joy (0, 1) ; 
else 

HorDir i= a«i t Joy {0, 0) ; 
if SfcillFirino (0) > then FireQun; 

BASIC: 

IF OnALadder t THEN BEGIN 

TOOLBOXC-QetJoy i 0, 0, 1; VertDir%) 
ELSE BEGIN 

TOOLBOX ("Oet Joy I 0, 0, 0; HorDir%) 
ENDIF 

TOOLBOX(-'StlllFirinff i 0, 0; Buttons%) 
IF Buttone% > THEN GOSUB FireGun 



4.3 Game and Network Drivers 

The newest version of DrawTools will let these 3 tools work with devices other than a joystick provided you 
have a game driver. A game driver in DrawTools operates a substitute device for a joystick, like the keyboard or a 
trackball. Up to 4 game drivers can be u.sed at one time. (For more information on how game drivers work, consult 
Appendix D of the reference.) 

Three sample game driver is included in the DT.Drivers folder on the I>rawTools' disk: 

Joystick. Drvr - simply operates the IIGS joystick using GetJoy, GetFire & StiilFiring 
Keypad.Drvr - simulates a joystick on the IIGS keyboard (with the Event Manager's GetNextEvent) 

• keys 1...9 specify your direction 

• 0, +, * are fire buttons 0, 1,2, and 3 respectively 

• , allows you to change your speed (-2,0,+2) or (-1 ,0,+l) i 
Keypad.Drvr - simulates a joystick on the IIGS keyboard (with the Event Manager's GetNextEvent) 

• keys y,u,i,hjjc,b,n,m specify your direction 

• space,a,s,d are fire buttons 0, 1, 2, and 3 respectively 

• f allows you to change your speed (-2,0,+2) or (-I,0,+1) 

Not all languages support the system loader directly; to load a driver, you can use LoadDriver. To start the 
driver, use the DrawTools' SetGameDriver tool. 

Example ; Loading and starting a game driver (as device #1). 

Pascal: 

DriverPtr i= LoadDrlv«r( DriverPath ); 
3«tCt«inaDrlvttr < 1, driverPtr ) ; 

BASIC: 

REM LoadDriver requires a Pascal string. 

TOOLBOXC-IioadDrivor t 0, 0, PathH%, PathL%; DriverPtrL%, Driv6rPtrH%) 
T00LBOX(-'fletO«m«Drlver 1 1, DriverPtrH%, DriverPtrL%) 

Now whenever you use GetJoy, GetFire or StiilFiring with a 1 (not 0) as the first parameter, DrawTools' will 
use the new device in place of a joystick. 
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There is also a second kind of driver you can install, a net driver, tliat keep you informed of devices operating on 
other lIGS's across a computer network or a modem. 

Example : You are writing a Tetris™ clone to work with 2 players on a network. The object of the game is to be the 
player who survives the longest. What we need to do is: 

(1) use SendNet^vo^k to synchronize the start of the ganie on two different computers 

(2) use SendNetwork to find out who "died" first. 



Pascal: 

Const AbortGame = 8; 

QameAborted = 1; 
ReadyToGo = 16; 

NoQnd = 0; 
Var Qnd i integer; 

Data t integer; 



{SendNetwork code to abort a game] 

{S.N. code for someone aborting a gcrniej 

{define our own code to eignal} 

{ that we're ready to begin playing) 

(S. N code for no canmand} 

{ SendNetwork coimand word } 

[ S.N. data word 3 



begin (main program) 

{ do any initialization J 

repeat 

Qnd t= ReadyToGo J 

S*ndK«twork( Cmd, Data ); 

if Qrd <> ReadyToGo then Qnd »= NoQnd; 



{signal the other IIGS that) 

{ we are ready 3 

{ check the network 3 

(ignore everything unless other IIGS} 

{ is ready, too) 



until Qnd = ReadyToGo; 

{ both IIGS's will only get here by both sending "ReadyToGo" over the } 
{ network. This process ie scmetimeB called "handshaking" 1 
ImDead i= false; 
repeat 

{ do the Tetris stuff in here ) 
if ImDead then 

Qnd 1= AbortGame; 
else 

Qnd (= NoQnd; 
SendNebvork( Qndj Data ) ; 
until ImDead or (Qnd = GameAborted) ; 
if ImDead then 

Vft-iteliiCYou lost to the other player.') 

else 

WriteLn ( 'You won ! 1 ' ) ; 

end; 



( if player "died" /lost 3 
{ inform other GS that we lost first ) 

{ else just check tke network } 

{ done if dead or other player dead ) 



4.4 Printing Tools 

For assembly language programs, these are a simple set of tools for displaying Pascal strhigs and integers on 
the super hi-res screen, Several of the printing tools have a mode word that comes ai^er the rest of the parameters: 
with this mode word, you can specify whether you want a carriage return, the rest of the line to be cleared, or if you 
want to tab over to a new column. 



Example : Printing in assembly language. 

Merlin 16+: 

_Ready2 Print 



; in any new grafport, use _Ready2Print 
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_Hcine 

-Print jiSfcringi;#0 
-Printint #$1234 ;Jf$8000 
-Print #String2;#$8000 



Stringl str 'The number is ' 
String2 str 'All done.' 



Output: 

The number ie 4660 
All done. 



heme the cursor to top of screen 
display Pascal string Stringl 
display value of $1234 & do a C/R 
display String2 and do a C/R 



4 . 5 Interrupt Tasks 

In Siiper-Hi-Res graphics mode, the computer can be intemipted when a certain line is about to be drawn by the 
monitor and perform some quick task. By using interrupts, you can, for instance, have several different border 
colours, or can cause different sets of palettes to be available (512 coloiirs or more instead of 256). Each task has a 
task header, which, strangely enough, need not be at the head of the task at ail. A task could have more than one 
header, one for each line which is to invoke the task. Needless to say, don't touch the header if the task has been 
added. Once you've defined (and, hopeftilly, debugged before hand) your tasks, enable the intemipts 
(EnableSCBInts), add the tasks (SetSCBInt), and start the execution of the tasks (ResumeSCBInts). 



Example : How to put 512 colours on the a;reeQ instead of only 256. 

To do this, we need two sets of 16 palettes; one for the top half of the screen, and one for the bottom half. We can 
use the interrupt tools to switch the palettes around. Once _ResumeSCBInts is used, the palettes will be swapped 
"in the background", and the main program can do other things. 

Merlin 16+: 

"EnablvSCBInfcs #-1 
~S*bSCBInt #r.ine99Header 
"8«tSCBIiit #Linel99Hea.dsr 
R«sum«SCBZnts 1 

Lines 9 Header adrl 
dw 99 
dw $D44D 

adrl SwapPalettee 
Ijinel99H6ader adrl 
dw 199 
dw $D44D 

adrl SwapPalettee 

SwapPalettes 

phd 
phb 

* swap, in and out, the 16 palettes here 
plb 
pld 
rtl 



J reserved 

;the line this header applies to 
J signature word 

; invoke svsp palettes on line 99 



; invoke again at 199 
;our interrupt task 
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4.6 ScoUing the Screen 



The lIGS is too slow to scroll a screen quickly enough without ugly, slanting jaggies appearing as different 
portions of the screen are at different stages of scrolling. DrawToois has a couple of screen scrolling tools to shift 
the screen contents and fill the void created with a picture. To scroll faster, the screen is divided up into small 
blocks: if two adjacent blocks look the same, they are left alone; if they differ, they are scrolled. The result is that it 
appears that the whole screen is scrolling, but only the portions that need to be moved are moved. 



Fi gure 7: A Scrolling Block 
Check Byte 







Each block is four bytes wide, and eight bytes high; on the screen, that's up to 40 blocks across, 25 blocks 
down. The upper-left byte in a block is called the check byte. If the check bytes of two adjacent blocks match, the 
blocks are assumed identical and no scrolling takes place. Obviously, not every picture can be scrolled using this 
method. Pictures must be caref\illy constructed, making sure the check bytes differ whenever a block differs from a 
neighbour. By this method, and clever art work, a picture can be made to look smooth and natural, and still scroll 
very quickly. 

Q| You can make two check bytes look the same but be treated as differing by using a pixel whose colour is 
/ \ equal to another (eg. two greens {fflJH) of the same shade; one check byte can use green #1, and the other 
green #2 - they look the same, but they are actually different byte values). 

The scroll tools use a scroll record, containing a description of the area of the screen te scroll, and of the picture 
to be scrolled in. Scrolling may extend between any two screen lines, provided that the range is composed of 
complete blocks (8 lines each). The scroll record parameter for width allows any rectangular picture to be scrolled 
onto the screen, A screen wide picture has a width of 160; DrawToois pictures have a width of 12, 



4.7 Other Tools 

DrawToois has a variety of other tools that may be usefiil in many programs. 

• the work cursor, a pair of rotating gears, an alternative to the watch cursor, 

• HLoad and HSave, to quickly and easily load files to handles and vice versa. 

• a bar graph drawer 

• a tool that let's assembly language programs call certain tools at faster speeds 

• GetMHz returns the speed of the GS to the nearest MHz 

• a tool to print windows or the screen on your printer 

Example : How to use the work cursor, 

Pascal: 

WorhCuraorS (6) ; {aniniate the work cursor every 1/lOth seccndj 
for i t= 1 to 20000 do begin (StillWbrking calls) 
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j >= j + i; 
StillHorking; 

end; 

InitCursor; 

BASIC: 

TOOLBOX(-WorlcCurooir2 : 6) 

FOR i% = 1 10 20000 
3% = j% + i 

TOOrBOXf-StillWorkintr ) 

NEXT i% 

TOOLBOX (4, 202) 

Merlin 16+: 

"WorkCurflora #6 

LDA tt20000 
STA i 
loop INC j 

StillHorJcing 

DEC i 

BNE loop 

_lnitCursor 

Example : Drawing a packed super hi-res screen (filetype $C1/$0001). This format is used by 8/16 Paint™ Screen 
Pictures and DreamGraphix^ " PackBytes 16/256. For other programs, save the picture as an unpacked screen and use 
Lib.Converter 1 .2 to convert the picture, 

TML/Complete Pascal: 

P2GSString( 'MyPlc' , pathetr ); 
PicHandle t= HLoad(pathstr, $C1) ; 
3otB«okground2 { PicHandle, ); 

ORCA/Pascal: 

PathStr.size <= length ( 'E<lyPiG' ) ; 
PathStr . theString t= 'MyPiC ; 
PicHandle i= HLo«d (pathstr, $Ci) ; 
S*tB«okground3 ( PicHandle, ); 

BASIC: 

REM Basic doesn't support es/OS strings directly 

REM Use GET_MEM to get 337 68 bytes, and load the picture vd.th BLOAD. 
TOOLBOX( ~S«tBackgrouiid2 t PicH%, PicL%, ) 

Merlin 16+: 

PathStr 8trl 'MyPic' 

-HLo*d itPathStr; #$C1 
S»tBKakgcound2 j handle is still on the stack 
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11. Reference 



Introduction 



This is section explains the layout of the reference section, and defines some of the terms used. For a more 
general introduction to DrawTools, please read DrawTools Introduction manual. 



Layout of Tool Entries 



DrawTools provides over 100 tools, For convenience, these tools are divided up into different categories by use: 

Housekeeping Tools, Low-level DrawTools, Drawing Tools, Library Management Tools, Animation Tools, 
Screen Tools, Scrolling Tools, Palette and Colour Tools, SCB Interrupt Tools, Printing Tools, Driver Tools 
and Miscellaneous Tools. 



Each individual tool is described in tlie following format: 



PrawVersion ($0462) 

Retiuns the version number of DrawTools, 

Examples : int := DrawVersion; 

TOOLBOX( 98, 4 : 0; int% ) 
Parameters : int (word) - the version, ie. $0301 
Errors ; none 



Tfw tool name and number. 

A description of its use. 

An example in Pascal & BASIC. 

(BASIC: Include O's for each result word'.) 

A description of each parametei: 

A description ofeany errors it may return. 



Definitions of Terms 



Here's an explaination of some of the terras you may encoimter; 

Absolute Screen Position; A pixel number, 0,. ,3 1999; ASP = ( x / 2 ) + y * 160. 



Pixel 
Pixel 160 



Pixel 159 (159, 0) 



Pixel 31999 (319, 199) 



Booleans & BASIC: Treat the booleans as an integer: means false, and anything else is tnie. 

Bound lines: Bound lines are used to specify a range of screen lines. In DrawTools, bound Imes need not be in 

ascending order. 

Colour word: An RGB colour word of the form $ORGB, where R,G,B are the amounts of red, green & blue. 
Current Drawing Screen: Some tools will work with either the shadow screen or main screen, whichever is 
active. 

Library buffer; a 9K area in back where recently used libraries are kept. 
Main Screen: the slow drawing area in back $E1, used by most applications. 
Nil pointers & BASIC: use zeroes. 
Shadow Screen: the fast drawing area in bank $01. 
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Housekeeping Tools 

These are the standard tools in every toolset. 



DrawBootlnit ($0162) 

Should never be calied by an application; does nothing. 
Examples : should never be called. 

Parameters : none 
Errors : none 

DravvStartUp (S02621 

Starts up DrawTools for use by an application. It must be made before any other DrawTools call. It does the 
following: 

* Searches for the special QuickDraw locations 

* Saves user ID with auxiliary type $F (used for all memory allocation, including HLoad's & LoadLibrary's) 

* Allocates one library buffer (about 9K in bank 0) 

Examples : DrawStartUp( dpage, MNflD ) 

TOOLBOX( 98, 2 : dpage%, MMID% ) 
Parameters : dpage (word) - address of direct page workspace 

MMID (word) - memory manager ID of your application 
Errors : none 



DrawShiitDown ($0362) 

Shuts down DrawTools when an application quits. This routine does the following: 

* Ensures the system interrupt manager is in its normal state 

* Deallocates all memory us«l (including HLoaded handles & picture libraries) 

* Shuts down the net driver, if one is installed 

* Restores shadowing to its original state 

Examples : DrawShutDown; 

TOOLBOX(98,3) 
Parameters : none 
Errors : none 

DrawVersion (S0462) 

Returns the version number of DrawTools. 

Examples: int := DrawVersion; 

TOOLBOX( 98, 4 : 0; int% ) 
Parameters : int (word) - containing $0301, meaning version 3,1 
Errors : none 
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DrawReset f$0562) 

Resets DrawTools; disables SCB interrupts. This tool must not be used by an application. 
Examples : should never be cal led 

Parameters : none 
Errors : none 

DravvStatiis f$06621 

Indicates whether DrawTools is active. 

Examples : bool := DrawStatus; 

TOOLBOX( 98, 6 : 0; bool% ) 
Parameters : bool (word) - TRUE if DrawTools has been started up. 

Errors : none 



I 
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Low-LevelTools 

These are tools for changing DrawTools' parameters and/or performance. 



KxtftndBnffers f$4A62) 

Allocates as many library buffers as possible. Use this to reduce the time it takes to switch between picture libraries 
in graphic intensive programs (like games). 
Examples : ExtendBuffers; 

TOOLBOX(98, 74) 
Parameters : none 

Errors : $6209 - not enough bank memory for another buffer 

$620 A - already have maximum number allocated 

RfisefBnffers ($7062) 

Clears the library buffers. The library buffers act as a caching mechanism for libraries: ResetBuffers clears the cache 
memory. Use this when you are going to usuig a new set of libraries. For example, when you begin a new level in 
a game, ResetBuffers will let you access new level libraries more efficiently. 
Examples: ResetBut¥ers; 

TOOLBOX(98, 112) 
Parameters: none 
Errors: none 

( 

nraxvPns ($0B62) 

Returns the absolute screen position for the next bit-mapped picture call. 
Examples : int := DrawPos; 

TOOLBOX(98, 11 : 0; int% ) 
Parameters : int (word) - 0...3 1999 

Errors ; none ' 

SpiPrawPos ($0C62) 

Sets the absolute screen position for the next bit-mapped picture operation. 

Examples : SetI>rawPos( int ); 

TOOLBOX( 98, 12 : int% ) 
Parameters : int% (word) - 0..,3 1999 

Errors : $62FF - the position is off the screen 

DrfiwPflt xe (SQD62) 

Returns the location of the buffer for the current picture library. 
Examples : int% - DrawPage; 

TOOLBOX(98, 13:0;int%) 
Parameters : int (word) - the bank location of the active set of pictiu-es 
Errors : none 
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SetPrawPage f$0E62) 

Sets the location of the current picture buffer. 

Examples : SetDrawPage ( locn ); 

TOOLBOX( 98, 14 : Iocn% ) 
Parameters : iocn (word) - the bank location of the active set of pictures 

Errors : none 



DrawMatn ($0F62> 

Directs DrawTools to use the main screen (bank $E1). The current grafporf is also forced to the main screen. 
Examples : DrawMain; 

TOOLBOX( 98, 15 ) 
Parameters : none 
Errors ; none 



DrawShadow f$l()(i2> 

Directs DrawTools to use the shadow screen (bank $01). The current grafport is forced to the shadow screen instead 
of the main screen. Micol Advanced BASIC'S shell uiterferes with this command, but it will work in stand-alone 
applications. 

Examples : DrawShadow; 

TOOLBOX(98, 16) 
Parameters ; none 
Errors : none 



J 
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Drawing Tools 

These tools draw bit-tniipped pictures from picture libraries, or produce masks 
for matted bit-mapped pictures, without any animation, if you are using pixies, 

see the animation tools. 



Draw f$0962) 

Draws a 24x24 bit-mapped picture at the current screen position and advance to the right. 
Examples ; Draw{ pic ); 

TOOLBOX(98,9:pic%) 
Parameters : pic (word) - picture in the current library (0...3 1) 

Errors : none 



Draw48 f$0A62) 

Draws a 48x48 bit-mapped picture at the current screen position and advances to the right. 
Examples : Draw48( pic ); 

TOOLBOX( 98, 10 : pic% ) 
Parameters : pic (word) - picture in the current library (0,.28) 

Errors : none 

DrawAt ($1462) 

Draws a 24x24 bit-mapped pictiue at the specified screen position and advances to the right. 
Examples : DrawAt( xco, yco, pic ); 

TO0LB0X( 98, 20 : xco%, yco%, pic% ) 
Parameters : xco (word) - x-coordinate (0..3 19) 

yco (word) - y-coordinate (0...199) 

pic (word) - picture in the c\irrent library (0„31) 
Enors : none (if bad coordinates are used , the picture is drawn at the upper-left coma-) 

I)raw48At ($1562) 

Draws a 48x48 bit-mapped picture at the specified screen position and advances to the right. 
Examples : Draw48At( xco, yco, pic ); 

TOOLBOX( 98, 21 : xco%, yco%, pic% ) 
Parameters : xco (word) - x-coordinate (0..3 19) 

yco (word) - y-coordioate (0.„199) 

pic (word) - picture in the current library (0..28) 
Errors : none (if bad cowdinates are used, the picture is drawn at the upper-left comer) 

DrawOn ($2262) 

Draws a matted 24x24 bit-mapped picture at the cxirrent screen position and advances one position to the right. 
Examples : ]>rawOn( pic ); 

TOOLBOX(98, 34 : pic% ) 
Parameters : pic (word) - picture in the current library (0..30) 

Errors ; none 



DrawToois 3.1 



35 



Draw480n f$2362) 

Draws a matted 48x48 bit-mapped picture at the current screen position and advances to the rigiit. 
Examples ; Draw480n( pic ); 

TOOLBOX{ 98, 35 : pic% ) 
Parameters : pic (word) - picture in the current library {0..24) 

Errors : none 

DrawOnAt ($2462) 

I>raws a matted 24x24 bit-mapped picture at the specified screen position and advances to the right. 
Examples : DrawOnAt( xco, yco, pic ); 

TOOLBOX( 98, 36 : xco%, yco%, pic% ) 
Parameters : xco (word) - x-cooidinate (0,.3 19) 

yco (word) - y-coordinate (0„.i99) 

pic (word) - picture in the current library (0..30) 
Errors ; none (if bad coordinates are used, the pichire is drawn at the upper-left comer) 

Draw480nAt ($2562) 

Draws a matted 48x48 bit-mapped picftire at the specified screen position and advances to the right. 
Examples : Draw480nAt( xco, yco, pic ); 

TOOLBOX( 48, 37 : xco%, yco%, pic% ) 
Parameters ; xco (word) - x-coordinate (0..3 19) 

yco (word) - y-coordimite (0...199) 

pic (word) - picture in the current library (0,.24) 
Errors ; none (if bad coordinates are used, the picture is drawn at the upper-left corner) 

GenMask ($2162) 

Generates a matting mask for the specified picture and stores it in the next picture position. 
Examples : GenMask( pic ); ^ 

TOOLBOX(48,33:pic%) 
Parameters : pic (word) - picture in the current library to make a mask for (0,.30) 

Errors : none 

GetAllMasks ($2662) 

Generates a matting mask for every even-numbered picture in the current picture buffer, storing each mask in the 
following odd-numbered picture position. 
Examples : GenAllMasks; 

TOOLBOX(48, 38) 
Parameters ; none 
Errors ; none 
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Setnack grourKlt ($3962) 

Draws a packed super hi-res screen (filetype PNT/$0000) on the current drawing screen. The handle is left unlocked. 
Examples : SetBackgroimd( Background ); 

TOOLBOX( 98, 57 : BackgroundH%, BackgroundL%) 
Parameters : BackgroundHandle (long) - handle to packed picture 

Errors : memory manager errors 

t See SetBackround2, 

Wipp.Ont ($5562) 

Wipes a 24x24 block of pixels from the shadow screen to the main screen at the current drawing position. 
Shadowing must be enabled. 
Examples : WipeOn; 

TOOLBOX( 98,85) 
Parameters : none 
Errors : none 

t For use with pixies, see ErasePixie and EraseAIlPixies, 
SfitBackgrQu nd2 f$6F62) 

Draws a packed super hi-res screen (filetype PNT/${XX)0) on (he current drawing screen. You can create this kind of 
picture by packing a super hi-res screen with PackBytes, or using one of several IIGS graphics conversion utilities 
that are available, or by saving an S/lfi-Paint™ picture as a screen. The handle is left unlocked. 
Examples: SetBackground2( Background, Flags ); 

TOOLBOX(98, 111: BackgroundH%, BackgroundL%, Flags% ) 
Parameters: Backgroimd (long) - handle to the packed screen 

Flags (word) - list of options; 

- normal (}ik& SetBackground) 

1 - pixels and SCBs only (no palettes) for QuickWipe or VBWipe 

2 - ready to fade in with QuickFadeIn or IncrFadeln 
Errors; memory manager errors 
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Library Management Tools 

Tools used in loading and using picture libraries. 



LoadLihrarv ($2B62) 

Retrieves a DrawTools picture library from the disk and returns its library ID number. 
Examples : LiblD ;= LoadLibrary( path, SeqlibNum, packed ); 

TOOLBOXC 48, 43 : 0, PathH%, PathL%, SeqLibNum%, Packed% ; LibID% ) 
Parameters : path (long) - GS/OS path name pointer 

SeqLibNum (word) - logical number for pixie sequence commands (else just 0) 

Packed (word) - bit 15 - TRUE if the library is packed with PackBytes 
- bit 14 - TRUE if GenAllMasks should be called before library is used 

LibID (word) - the ID numba' for the library 
Errors : $6201 - too many libraries loaded (current limit is 24) 

$6202 - SetiLibNum is out of range 

GS/OS and Memory Manager errors 



UnloariLihrary fS2E62) 

Deallocates a library loaded with LoadLibrary. Normally, DrawShutDown automatically unloads all libraries. 
However, this tool allows you to manually discard a library you no longer need without shutting down DrawTools. 
Examples : Unloadlibrary (LibID); 

TOOLBOX( 48, 46 : LibID% ) 
Parameters : LibID (word) - the ID of the library to imload 

Errors ; $6203 - mvalid library ID number 

$6204 - the library isn't loaded 

Memory Manager errors 

SfttLihrarv fS2C62) 

Makes the specified library the current one use with the drawing or animation tools. 
Examples ; SetLibrary( LibID ); 

TOOLBOX( 48, 44 ; UbID% ) 
Parameters : LibID (word) - the ID of the library to make current 
Errors : $6203 - invalid library ID number 

$6204 - the library isn't loaded 

Memory Manager errors 

Gg t3Lit) r a ry ($2D62 ) 

Returns the library id of the current library, 

Examples ; LibID := GetLihrary; 

TOOLBOX( 48, 45 : 0; LibID% ) 
Parameters : LibID (word) - the ID of the currait library (-1 if none) 

Errors : none 
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Animation Tools 

Tools used in animating objects & handling animarion sequences, 



Fine Pixie Data Record: 
0,1 - X Vector Low (word) 
2,3 - X Position Low (word) 
4,5 -X Vector Hi (word) 
6,7 - X Position Hi (word) 
8,9 - Y Vector Low (word) 
10,11 - Y Position Low (word) 
12,13 -Y Vector Hi (word) 
14,15 - Y Position Hi (word) 

16 - Index (byte) 

17 - Status (byte) 



Coarse Pixie Data Record: 
0,1 - Vector (word) 
2,3 - Position (word) 

4 - Index (byte) 

5 - status (byte) 

Simple Pixie Data Record: 

- Index (byte) 

1 - Last Frame (byte) 



IB 



When you aniniate a pixie, tiie new pixie position is calculated by adding the vector value to the position 
value, resulting in the new position. For example, a fine pixie with an x vector of 1 (hi 1, low 0) and an 
original x position of 10 (hi 10, lo 0) will move to x position 1 1 the next time it is animated. 



Sequence Description 
Byte 

0..,3 1 picture to use in current library 

32.. .247 resaved 

248 change status byte 

249 change fine pixie dir relative 

250 change coarse pixie direction 

251 change fine pixie direction 

252 change fine pixie y direction 

253 change fine pixie x direction 

254 change library 

255 end of sequoice 



Parameter Bytes Followng Byte 



new status (byte) 

X & Y vectors to add to current vectors (4 words) 

new direction (word) 

new X & Y words (4 words) 

new Y words (2 words) 

new X words (2 words) ' 

LoadUbrary logical number (word) 

position to resume at (byte) 



For simple pixies, any negative byte (128 or bigger) is considered an end of sequence command. 



NewPixie ($3A62) 

Returns a number of a pixie that's not in use. Wlien allocating several pixies, remember to use SetPixie after each 
NewPixie, or NewPixie will return the same number each time. -1 is returned if no pixie is firee. 
Examples : MyPixieNum := NewPixie; 

TOOLBOX( 98, 58 : 0; MyPixieNum% ) 
Parameters ; MyPixieNum (word) - the pixie number (0...15) 

Errors : none 
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ClearPixie f$3B62) 

Deallocates tlie specified pixie table position. 

Examples : ClearPixie{ MyPixieNum ); 

TOOLBOX( 98, 59 : MyPixieNura% ) 
Parameters: MyPixieNum (word) - thepixiemimber (0...15) 

Errors : • $62FF - the pixie number is out of range, or the position is already free 

Set Pixie iUE(t2) 

Sets up a pixie for use. If that pixie already exists, the old pixie is overwritten. 

Examples : SetPixie( pixnum, pixiedesc, pixiepfr ); 

TOOLBOX( 48, 78 : pixmim%, pixiedesc%, pixieptrh%, pixieptrl% ) 

Parameters : pixnum (word) - the pixie number (0.. 15) 

pixiedesc (word) - description of the pixie: 

bit 15 - pixie visible (TRUE) or invisible (FALSE) 
bit 14 - pixie matted (TRUE) or not matted (FALSE) 
bit 3-13 - reserved, set to 
bit 0-2 - pixie type (0=simpie, l=coarse, 2=fine) 
pixieptr (long) - pointer to the pixie data record 

Errors : $62FF - pixie number is out of range 



GetPixift ($4F62) 

Returns a pointer to the specified pixie's data record. 
Examples : PixiePtr := GetPixie( PixieNum ); 

TOOLBOX( 98, 79 : 0, 0, PixieNum%; PixiePtrL%, PixiePtrH% ) 
Parameters : PixieNum (word) - the pixie number 

PixiePtr (long) - pointer to the pixie data record 
Errors ; $62FF - pixie number is out of range 

SfitPixifiSeq f$2A62) 

Assigns the specified animation sequence to a pixie; any old sequence is overwritten. T)i& sequence index (in 
pixie data record) is not changed. 

Examples : SetPixieSeq( PixieNum, LibID%, SeqPtr ); 

TOOLBOX( 98, 42 : PixieNum%, Uh\D%, SeqPtrH%, SeqPtrL% ) 
Parameters : PixieNum (word) - the pixie number 

LibID (word) - the default picture library 

SeqPtr (long) - pointer to the animation sequence 
Errors : $62FF - pixie number is out of range 



GfttPixieSfiqf$.S062) 

Returns the pointer to a pixie's animation sequence. 
Examples : SeqPtr := GetPixieSeq( PixieNum ); 

TOOLBOX( 98, 80 : 0, 0, PixieNum% ; SeqPtrL%, SeqPtrH% ) 
Parameters : PixieNum (word) - the pixie number 

SeqPtr (long) - pointer to the animation sequence 
Errors : $62FF - pixie nimiber is out of range 
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HidePixie f$5262) 

Stop drawing a pixie on subsequent aniniation calls, but continue animating it as if it were visible, 
Examples : HidePixie( PixteNum ); 

TO0LBOX{ 98, 82 : PixieNuni% ) 
Parameters : PixieNum (word) - the pixie number 

Errors : $62FF - the pixie number is out of range 



ShnwPixift ($5162) 

Draw a pixie on subsequent animation calls. 

Examples : ShowPixie( PixieNum ); 

TOOLBOX( 98, 81 ; PixieNum% ) 
Parameters : PixieNum (word) - the pixie number 

Errors : $62FF - the pixie number is out of range 



nisflhlfiPixie ($2862) 

Stop animating a pixie on subsequent animation calls. 
Examples : DisablePixie( PixieNum ); 

TOOLBOX( 98, 40 : PixieNum% ) 
Parameters : PixieNum (word) - the pixie number 

Errors : $62FF - the pixie number is out of range 



KnahlePixie ($2962) 

Animate a pixie on subsequent animation calls. 

Examples : EnabIePixie( PixieNum ); 

TOOLBOX( 98, 41 : PixieNum% ) 
Parameters : PixieNum (word) - the pixie number 

Errors : $62FF - the pixie number is out of range 



AnimatePixie ($5362) 

Animate a single pixie one pkt\ac along its sequence. Unlike Animate, you will have to use SetLibrary to select 
the picture library for the pixie. The drawing position for the drawing tools is unaffected. 
Examples : AnimatePixie{ PixieNum ); 

TOOLBOX( 98, 83 : PixieNum^ ) 
Parameters : PixieNum (word) - the pixie number 

Errors : $620C - Command for a different kind of pixie (disables pixie) 

$620D - Undefined command in sequence (disables pixie) 
$620E - Pixie doesn't exist 
$62FF - Pixie number is out of range 
SetLibrary errors 



Animatp. ($2762) 

Animates all of the pixies one pichire along their sequences. The drawing position for the drawing tools is 
unaffected, 

Examples : Animate; 

TOOLBOX(48,39) 
Parameters : none 
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Errors : $620C - Command for a different kind of pixie (disables pixie) 

$620D - Undefined comniand in sequence (disables pixie ) 
SetLibrary errors 

Krasp.Pixie ($6B62) 

Erases the specified matted pixie with the corresponding contents of the siiadow screen. 
Examples: ErasePixie{ Pixie ); 

TOOLBOX(98, 107: P(xie%) 
Parameters: Pixie (word) - the pixie number 

Errors: $620E - Pixie doesn't exist 

$62 1 1 - Not a matted pixie 

$62FF - Pixie nutnber is out of range 



KraseAIIPixies ($6C62) 
Erases all enabled, matted pixies, 
Examples: EraseAllPixies; 

TOOLBOX(98, 108) 
Parameters: none 
Enrors; none 
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Screen Tools 

Tools involving the screen, including those involving shadowing and the SCBs. 



CLSt ($3462) 

This tool acts the same as QuickDraw IP's ClearScreen, 
Examples : CLS ( ColourWord ); 

TOOLBOX( 48, 52 : ColoHrWord% ) 
Parameters ; ColonrWord (word) - word to fill the screen with 

Errors : none 

t Before System 6.0, ClearScreen would not clear the shadow screen; CLS works fine on older systems. 
OnickWipe f$lC62) 

This tool copies the shadow screen to the main screen. 
Examples : QuickWipe; 

TOOLBOX( 48,28) 
Parameters ; none 
Errors : none 

VBWipe ($3562) 

This tool copies the shadow screen to the main screen using a "Venetian blind" effect, 
Examples : VBWipe; 

TOOLBOX(48, 53) 
Parameters : none 
Errors ; none 



FadeUone (S4C62) 

Returns TRUE if a fade is finished fading, hi the current version of DrawTools, all fading occurs during the In/Out 
call; future versions will fade during the FadeDone calls to allow animation to continue during the fading process. 
For compatibility, always have a REPEAT... UNTIL FadeDone (or the equivalent in your language) immediately 
after using a fade tool. 
Examples: done := FadeDone; 

TO0LBOX( 98, 76 ; 0; done% ) 
Parameters : done (word) - TRUE if the last fade has betsi completed 

Errors : none 

QnickFadeOut/In ($16/1762) 

Fades the colours in the first eight palettes to black, or restores them to their original values. The upper eight 
palettes are used to store the original palettes. 
Examples : QuickFadeIn( rale ); 

TOOLBOX( 48, 22 ; rate% ) 
Parameters : rate (word) - (t 60th's of a second betweai INCs/DECs 

Errors : none 
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IncrFadeOut/In f$18fl9<i21 

Fades the colours in the tirst eight palettes to red, then to black, or restores them to their original values 
{"incremental fade"). The upper eight palettes are used to store the original palettes, 
Examples : IncrFadeIn( rate ); 

TOOLBOXC 48, 24 ) 
Parameters : rate (word) - ff 60th's of a second between INCs/DECs 

Errors : none 

ShadnwOn f$1262) 

This tool enables the hardware shadowing of the shadow screen. If you open a new grafiport (using OpenPort) with 
shadowing enabled, the port will !» assigned to the shadow screen. 
Examples ; ShadowOn; 

TOOLBOX( 48, 18 ) 
Parameters : none 
Errors : none 



ShadnwOff ($1162) 

This tool disables the hardware shadowing of the shadow screen. If you open a new grafport (using OpenPort) with 
shadowing disabled, the port will be assigned to the main screen. 
Examples : ShadowOff, 

TOOLBOXC 48, 17 ) 
Parameters : none 
Errors ; none 



WaitVB ($1362) 

This tool passes time until the beginning of the next vertical blanking period (1/60 to 1/30 of a second). If you erase 
during a vertical planking period, you will have less flicker in your animation. 
Examples : WaitVB; 

TOOLBOX( 48, 19 ) i 
Parameters ; none 
Errors : none 



VVaitLine ($5E62) 

Tliis tool waits until your monitor is drawing a particular line, Use this to reduce flicker when you are drawing by 
waiting until an object is drawn on the monitor before erasing it. 
Example : WaitLine( line ); 

TOOLBOXC 98, 94 : line% ) 
Parameters : line (word) - line number to wait for, 0..199 

if line < 0, line is treated as 

if line > 199, line is treated as 200 (same as WaitVB) 
Errors: none 
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SefBnrder t$lF62^ 

This tool sets the colour of the screen border. 
Examples : SetBorder( Colour ); 

TOOLBOX( 48, 31 : Colour% ) 
Parameters : Colour (word) - the new colour (0... 15) as in the control panel 

Errors : none. 

This tool returns the current colour of the screen border. 
Examples : Colour := GetBorder; 

TOOLBOX( 48, 30 ; 0; Coiour% ) 
Parameters ; Colour (word) - the colour (0...I5) as in the control panel. 

Errors ; none 

SfitSCBs ($3662) 

This tool sets specific bits in the SCB's for a range of lines. This tool should not be used to change the mtemipt bit 

while the SCB interrupt handler is enabled. 

Examples : SetSCBs( linel, line2, BitsToSet ); 

TOOLBOX( 98, 54 : linel %, line2%, Bits% ) 
Parameters : linel (word) - first boiuid Ime 

!ine2 (word) - last bound line 

BitsToSet (word) - mask of bits to set (l=set bit) 
Errors : none 

( 

RpsfitSrns f$3762) 

This tool resets specific bits in the SCB's for a range of lines. This tool should not be used to change the interrupt 

bit while the SCB interrupt handler is enabled. 

Examples : ResetSCBs{ linel, Iine2, BitsToReset ); 

TOOLBOX( 48, 55 : lmel%, line2%, Bitsfo ) 
Parameters : line! (word) - first bound Ime , 

line2 (word) - last bound line 

BitsToReset (word) - mask of bits to reset (I=reset bit) 
Errors : none 
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Scrolling Tools 

Tools to scroll portions of the screen. 



The Format of a Scroll Record; 



0,1 


offset (word) 


byte offset into fill picture 


2,3 


width (word) 


width of the picture in bytes (eg. 160 for a screen image, 12 for DT pic) 


4-7 


fillpfc (long) 


ptr to picture to fill with 


8,9 


first (word) 


first (top) screen line to scroll 


10,11 


numblocks (word) 


number of 8 line blocks to scroll 


12-15 


reserved 


must be 



ScrollLinesL f$3062) 

This tool scrolls the indicated lines one block (2 words) to the left, and fills them from a specified picture. Hie offset 

is incremented by the width. 

Examples : ScrollLinesL( ScrollRec ); 

TOOLBOX(48, 48 : Scrol!RecH%, Scrol!RecL% ) 
Parameters : ScrollRec (long) - pointer to the scroll record 

Errors : $6206 - first line is out of range 

ScrollLinesR ($3162) 

This tool scrolls the indicated lines one block (2 words) to the right, and fills them with a specified picture. The 

offset is decremented by the width. 

Examples : ScrollLinesR( ScrollRec ); 

TOOLBOX{ 48, 49 : ScrollRecH%, ScrollRecL% ) 
Parameters : ScrollRec (long) - pointer to the scroll record 

Errors : $6206 - first line is out of range 



Note : The current version of ScrollLinesR will not work properly if the first line is'O, 
ScrollLinesU ($3262) (not available yet) 

This tool scrolls the indicated lines one block (2 words) to up, and fills them with a specified picture. The offset is 
incremented by a row of blocks 

ScrollLinesD ($3362) ^not available vet) 

This tool scrolls the indicated lines one block (2 words) to down, and fills them with a specified picture. The offset 
is decremented by a row of blocks. 
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Palette and Colour Tools 

Tools that change colours and manipulate palettes. 



SetPalette (Uk62) 

This tool sets the palette for a range of screen lines. 
Examples ; SetPalette( linel, line2, palette ); 

TOOLBOX( 48, 26 : llnel%, line2%, palette% ) 
Parameters ; line! (word) - first bound line 

line2 (word) - last bound line 

palette (word) - new palette number for lines (0,.i5) 
Errors : none (no range checking) 

This tool returns the palette assigned to a particular screen line, 
Examples : palette ;= GetPalette( line ); 

TOOLBOX( 48, 56 : 0, line% ; palette% ) 
Parameters ; line (word) - which line to check 

palette (word) - palette number for that line (0...15) 
Errors : none 

FadePfli (S1B62) 

This tool dims the source palette colours and stores them in the target palette. 
Examples ; FadePai( sourcepal, targetpal ); 

TOOLBOX( 48, 27 : sourcepal%, targetpal% ) 
Parameters :s ourcepal (word) - palette to fade (0...15) 

targetpal (word) - where to store (he faded palette (0,..15) 
Errors : none 



TInfadftPfll ($1D62) 

This tool brightens the source palette colours towards those in (he target palette. The colours are stored in the sourcg 
palette. 

Examples : UnfadePal( SourcePal, TargetPal ); 

TOOLBOX( 48,29 : sourcepal%, targetpal% ) 
Parameters : sourcepal (word) - palette to brighten (0...15) 

targetpal (word) - palette to compare with (0.. 15) 
Errors : none 
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SetColotir ($4062) 

Combines the red, green and bhie values into a colour word. 
Examples : word := SetColoiir( red, green, blue ); 

TOOLBOX( 48, 64 : 0, red%, green%, b!ue%; word% ) 
Parameters : word (word) - jxtletfe colour word 

red (word) - amount of red (0... 15) 

green (word) - amount of green (0...i5) 

blue (word) - anioimt of blue (0... 15) 
Errors : none. Bad values result in a meaningless coloiu" word, 

SetColPercent ($4162) 

Combines the red, green and blue percentage values into a colour word. 
Examples : word := SetColPercent( red, green, bhie ); 

TOOLBOX( 48. 65 : 0, red%, green%, blue%; word% ) 
Parameters : word (word) - palette colour word 

red (word) - percentage of red (0...1(X)) 

green (word) - percentage of green (0... 100) 

blue (word) - percentage of blue (0...100) 
Errors : none. Bad values result in a meaningless colour word. 

Elaboration: A few example RGB percent values (extracted from ACM SIGGRAPH '89 course notes); 



Gold 


78, 61, 16 


Old (dark) gold 


78, 43, 10 


Platinum 


83, 79, 56 


Silver 


81, 82, 70 


Antique (dark) silvCT 


53, 52. 47 


Steel 


55, 62, 59 


Copper 


97, 60, 28 


Brass 


69, 63, 23 


Iron 


18, 7, 6 


Sunlight 


100, 96, 92 


Moonligh 


75, 81, 100 


Naples Yellow 


100,66,7 


Cadmium Red (Ruby) 


89, 9, 5 


Brown Maddo' 


86, 16, 16 


King's Blue 


1,57, 76 


Indigo 


3, 18, 33 


Emerald Green 


0, 79, 34 


Teire-verte 


22, 37, 6 


Ivory Grey 


16, 14, 13 


Lamp Black 


18, 28,i23 



FindColour ($4262) 

This tool search the specified palette for the clasest colour to the one requested. 
Example ; colour := FindColour( numcol, palette, coIourWord ); 

TOOLBOX( 48, 66 : 0, mimcol%, palette%, colourWoid%; colourWord% ) 
Parameters : numcol (word) - 16 if 320 mode, 4 if 640 

colour (word) - the colour number of the closest colour 

palette (word) - the palette to search 

colourWord (word) - the palette colour word to match 
Errors : none 
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Blp.ndCnlQur f$SF62) 

Blends two colours together to form a new colour. 

Example : colour := BlendColoiir( weight, col 1 , col2); 

TOOLBOX( 98, 95: 0, weight%, coll %, col2%; coIour%) 
Parameters : colour (word) - the new colour word 

weight (word) - 0,.16, amoiuit of second colour to mix in 

col 1 (word) - the firsst colour word 

col2 (word) - the second colour word 
Errors ; $62FF - weight is out of range 

~f)] Elaboration; Some BlendColour Applications: 
}_ (1) Blending: colour := BlendColour(weight, coll, col2); 

(2) Bleaching (eg. for distance): colour := BlendColoHr(distance, col, backgroundcol); 

(3) Anti-aliasing: (a) colour := BlendColour(amount in pixel, colour, backgroundcol); (b) coiourNum := 
FindColour(i6, 0, colour); {for 320 mode} 

(4) Saturating: colour := BlendCoiourChow much to saturate, colour, $OF(X)); 



FfldfiCnlniir ($6062) 

Fades or brightens a colour. 

Example : colour := FadeColour(oldcolour, difference); 

TOOLBOX(98, 96: 0, oIdcolour%, difference%; colour%) 
Parameters : colour (word) - the new colour word 

oldcobur (word) - the original colour word 

difference (word) - (- 15) to (+15), amount to change the colour by 
Errors : None 



IB 



Elaboration: Some FadeColour Applications: 

(1) Darken colour; colour := FadeColoiufoldcolour,-!); 

(2) Brighten colour; colour := FadeColour(oldcolour, +1); 



FindPalette ($6162) 

This is my "mini Palette Manager" tool. Returns the coloiw numbers for the entries in the current palette which 
most closely resemble the colours that you expect in that palette. Especially useftil for NDAs, where you don't know 
what colours will be on the screen. FindPalette only recognises pure colours in 640 mode (not dithered colours). 
Example ; changed := FindPalette( colours, palette ); 

TOOLBOX( 98, 97: 0, coIoiu-sH%, coloursL%, paletteH%, paietteL%; changed%) 
Parameters : changed (boolean) - True if the coloiu^ have changed since last FindPalette 

colours (long) - address of a list of 16 coloiu- numbers corresponding to the colours in the palette 
palette (long) - address of palette (a QuickDraw II coloiTable) of desired colours 
Errors : none 
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Interrupt Tools 

Tools Involving SCB (or Horizontal Retrace, or Scan Line) Interrupts 



Format of a SCB interrupt task header: 



0-3 


longword 


TaslfPtT 


Use by tlie Interrupt Tools; do not modify 


4-5 


word 


Scan 


Line Line number of the task 


6-7 


word 


SigWoid 


signature word; always $D44D 


8-A 


3 bytes 


EntryPt 


task entry pointer 



Desig nin g an Intemipt Task : The task niust be a long subroutine (that is, end in an RTL instruction). B and D 
registers must be preserved, but other registers (A,X,Y J*) need not be, A task may have two or more headers if it is 
to be used on two different screen lines. Because DrawTools is non'reentrant, never call a DrawTools from a task 
unless your are sure the main program is not using DrawTools at the same time. 

IMPORTANT: (1) I have no idea why, but if you use the SCB intarupts, make sure you unload DrawTools before 
yoiu" program quits or the next program that nins will crash; at least, it happens with Merlin 16+ and EXE files -> it 
crashes during a Misc. Tools _GetVector call in DrawStartup. (2) When the intorupfs are enabled with 
EnableSCBlnts, do not switch the processor into emulation mode (e=l) without suspending interrupts (with SEI), 
The patch I placed on the intemipt manager is not designed to handle emulaticw mode IRQs, 

EnableSCBlnts (UM2) 

This tool must be used before all other SCB interrupt tools. Patches the system intemipt manager to use my SCB 
interrupt handla'. 

QuickDraw SCB intemipt use is suspended. The task list is cleared. 
Examples: EnableSCBInts( enable); 

TOOLBOX( 98, 74 : eaable% ) 
Parameters : enable (boolean) - TRUE if int^ipts are to be enabled 
Errors : nMie , 



SetSCBInt ($^062) 

Installs a SCB interrupt task for the given screen line. Automatically suspends all tasks until the next 
ResumeSC Bints. 

Examples : SetSCBInt( TaskPtr ); 

TOOLBOX( 98, 58: MachineLgH%, MachineLgL% ) 
Parameters : TaskPtr (longword) - pointer to the task header 
Errors ; $6205 - Task signature isn't $D44D 

$6206 - The screen line is out of range 

$6207 - A task already exists for that line 



DelSCBInt t$.^D62) 

Deletes a SCB interrupt task. Automatically suspends all tasks. 
Examples : DelSCBInt( TaskLine ); 

T0OLBOX( 98, 59 : TaskLine% ) 
Parameters ; TaskLine (mteger) - screai line of the task 

Errors : $6206 - The screen line is out of range 
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$6207 - A task doesn't exist for that line 



r.lrSCnints f$3E621 

Deletes all SCB interrupt tasks. Automaticaily suspends all tasks. 
Example : ClrSCBInts; 

TOOLBOX( 48,62) 
Parameters : none 
Errors ; none 

ResiimeSCBInts m¥62) 

Waits for the next vertical blanking period and resumes executing afl SCB interrupt tasks. 
Example : ResumeSCBInts; 

TOOLBOX(48, 63) 
Parameters : none 

Errors : $6208 - SCB interrupts not enabled 

$62FF - no tasks to execute 
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Printing Tools 

Tools to help assembly language programs write on the screen. 



Ready2Print ($56621 

This must be the first printing call in a new window (or grafport). Gets a pointer to the current graljxjrt, resets the 
margins to 0, and "homes" the QuickDraw pen. 
Examples ; '-Ready2Print 
Parameters : None 
Errors : None 



g^tlvTMargios ($5D62) 

Sets the left and top printing margins, Use Home to place the pen in the top-left comw of the new margin settings. 
Examples : "SetLTMargins #Left; #Top 

Parameters : Left (word) - left margin, in pixels 

Top (word) - top margin, in pixels 
Errors ; None 



Home ($57621 

Moves the QuickDraw pen to the left end of the first text line on the screen, like BASIC'S HOME. 
Examples : ~Home 
Parameters : None 
Errors ; None 



HTah ($5862) 

Moves the pen the specified number of pixels to the right of the left margin. 
Examples: -HTab#Indeat 

Parameters : Indrat (word) - number of pixels to indent 
Errors : Ncaie 



VTab ($5962) 

Moves the pen down the specified numbo* of screen lines from the top margin, based on the height of the current 
font. 

Examples: ~VTafa#NewLine 

Parameters : NewLine (word) - new screen line; 1 is the top line. 
Errors : $62FF - Newline was negative or zero 
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Print f$SAf)2) 

Draws a Pascal string on the screen, 
Examples : -Print Mr; #mode 

Parameters : str (long) - pointer to the Pascal string 

mode (word) - printing mode: 

bit 15 - TRUE if a carriage return is to follow printing 

bit 7 - tab to next column of 64 pixels after printing 

bit 6 - clear to end of the line 

other bits - reserved; set to 
Errors ; none 



PrintHftx ($5B62) 

Draws a hexadecimal value on the screen. 
Examples : -PrintHex ^number; #mode 

Parameters ; number (word) - the number to print 

mode (word) - same as with Print 
Errors : none 

Printint ($5C62^ 

Draws a signed integer value on the screen. 
Examples : -Printint ^number; Snwde 

Parameters: number (word) - the number to print 

mode (word) - same as with Print 
Errors : none 
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Driver Tools 

For a general discussion on game and network drivers, including how to design them, see Appendix D, 



LoadPriver fS6D62) 

Loads a specified game or net driver into memory. 
Example; DriverPtr := LoadDriver( DriverPath ); 

TOOLBOX(98, 109: 0, 0, DriverPafhH%, DriverPathL%; DriverPtrL%, DriverPtrH%) 
Parameters: DriverPath (long) - the Pascal string pathname 

DriverPtr (long) - pointer to the driver 
Errors: GS/OS errors 



UntoadPriver f$6E62) 

Unloads a specified game or net driver from memory. 
Example: UnloadDriver( DriverPtr ); 

TOOLBOX(98, 110: DriverPtrH%, DriverPtrL%) 
Parameters: DriverPath (long) - pointer to the driver to unload 

Errors: $62FF - imlcnown error while unloading 

SetCamePriver ($63621 

Installs a game driver for the specified player. 

Example : SetGameDriver( playearNiira, driverPtr ); 

TOOLBOX( 98, 99: playerNHm%, driverH%, driverL% ) 
Parameters : playerNum (word) - 1 . ,4, the player to use the game driver 

drivo'Ptr (long) - address of the game driver 
Errors : $62FF - DrawTools version is too low for this driver 

$620F - device number is out of range 

$6210 - The device this driver operates can't be found on the GS ' 
Se tNetPriver mUZ) 

Installs a network driver so that remote game drivers can be supported. 
Example : SetNetDriver( driverPtr ); 

TOGLBOX( 98, 98: driverH%, driverL% ) 
Parameters : driv^Ptr (long) - address of the net driver 

Errors : $62FF - DrawTools version is too low for this driver 

$6210 - Hie device this driver operates can't be foimd on the GS 

SendNetwork f$6462> 

Sends a message to the net driver and returns status information from the driver. The two parameters are used 
both. 

Example : SendNetwork( conmiand, data ); 

TOOLBOX( 98, 100: commandH%, commandL%, dataH%, dataL% ) 
Parameters : command (long) - address of the command; holds result after call 

data (long) - data for the command; data for the result 
Errors : $62FF - no net driver has been installed 
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Q SendNetwork commands: 

I \ Notes: (1) Commands marked with an asterisk (*) mark conmiaads called automatically by DrawToois when 
required. (2) "Post" is used m the sense of PostEvent in the Event Manager: transmits a message on the 
network or to the driver. 

- no command (use to poll the network) 

1 - request the number of remote players 

*2 - request the pseiido game driver addre.ss (returned in data) (used by SetNetDriver) 
*3 - post a new local player (data=player#) (used by SetGameDriver) 
4 - post a local player quitting (data=player#) 

*5 - post local GetToy result (data=device(bytel),axis(byte2),value(bytes3&4) (used by GetJoy) 

% - post local GetFire result (data=result) (used by GetFire) 

*7 - post local StillFiring result (data=Tesult) (used by StillFiring) 

8 - post abort game message (you can use it for whatever you want) 

*9 - init the net driver (used by SetNetDriver) 

* 10 - shut down the net driver (used by DrawShutDown) 

1 1-15 - reserved for ftiture use 

16-123 - application defined 

124 - set address of where to receive incoming data (data=address) (for 125... 127) 

125 - prepare to transmit (data=player(low), number of blocks to be sent(high)) 

126 - block transmit( data=pointer to 256 bytes (a "block")) 

127 - done transmit(data=player who should have received blocks) 

128 - driver will begin displaying status information on the screen (use DrawToois' Print tools) 

129 - driver will stop displaying status information 
130-255 - net driver defined. With the Null Network Driver: 

130 - fake a new remote player (#2) beginning to play 

13 1 - fade a remote player (#2) quitting 
>255 -reserved for fiiture use 

Results returned by SendNetwork: 

Note: only (null event) or orore should be returned during a block transmit or an information request, to avoid 
having to handle two things at once! 

- null event (nothing interesting happened) 

1 - abort game was received from a remote GS 

2 - a new remote player has started to play (data=player/0 

3 - an old player has quit playing (data=playei#) 

4 - bad connection (can't find the network) 

5 - bad networic error 

6 - network fiill (already 4 players playing) 
7-15 - reserved for fiiture use 

16-124 - you received an application defined event of same number (data=other information) 

125 - prepare to receive transmission (data=player(low), number of 256 byte blocks (hi)) 

126 - received 256 bytes of data (data=handle to data) 

127 - end of data (data=player who should have received data) 
> 126 - reserved for ftiture use 
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GetJov ($4362) 

Returns the jx)sition of the joyistick along one axis. Horizontally, left (-2) through right (+2); vertically, top (-2) 
through bottom (+2), There must be a 3 microsecond delay l>etween GetJoy calls, 
Examples : Position ;= GetJoy( Device, Axis ); 

TOOLBOX( 98, 67 : 0, Device%, Axis% ; Position% ) 
Parameters : Position (word) - the joystick position, -% ... 2 

Device (word) 

- for internal joystick, or 1..4 for a game driver 
Axis (word) - = horizontal axis ; 1 = vertical axis. 

- 2,3 - same, but for joystick #2 {device only) 
Errors : Axis value ANDed with 3. 

$620F - device number out of range 



GetFire ($4862) 

Determines which joystick fire buttons have been pressed (but not held dovm) since last GetFire/StillFiring). The 
button addresses were taken from the November '90 issue of "8/16". 



Examples ; 



Parameters : 



Errors : 



Buttons := GetFire( Device ); 

TOOLBOX( 98, 72 ; 0, Device%; Buttons% ) 

Buttons (word) - mask of fire buttons 

bit = 1 => button #0 is depressed 

bit I = 1 => button #1 is depressed 

bit 2 = 1 => button #2 is depressed 

bit 3 = 1 => button #3 is depressed 

bits 4 - 15 are zero 
Device (word) - for internal joystick, or 1..4 for a game driver 
$620F - device number out of range 



vStillFiring ($4D62) 

Determines which fire buttons are being held down, whether or not they were during the last GetFire/SfillFiring call. 
GetFire does not need to proceed a StillFiring call. 



Examples ; 



Parameters : 



Errors : 



Buttons := StillFiring( Device ); 
TOOLBOX( 98, 77 : 0; Buttons% ) 
Buttons (word) - mask of fire buttons 

bit = i => button #0 is depressed 

bit I = 1 => button ffl is depressed 

bit 2 = 1 => button #2 is depressed 

bit 3 = 1 => button #3 is depressed 

bits 4 - 15 are zero 
Device (word) - for internal joystick, or I . .4 for a game driver 
$620F - device number out of range 
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Miscellaneous Tools 



r.fttODT ($2062) 

Returns the Quick Dispatch Table (QDT), a set of 16 JML instniclions (64 bytes) to commonly used DrawToois 
routines. These are provided for assembly language programs that wish to avoid the overhead associated with tool 
calls. You must be in 16-bit native mode to execute the QDT routines. Jumping to a non-«xisted JML will cause 
unpredictable results, so check the toolset version before using GetQDT to ensure the JML's are available. 

Preparing a quick dispatch table: 

Draw adrl ; the quick dispatch table of 16, 4 -byte JML entries 

Draw48 adrl ; in ORCa/M use i4 

vector 16 adrl 

Pushptr Draw 
_GetQDT 

Using the quick dispatch table; 

LDA #ThePlc 
JSli Draw 

Register results after call: 
A - the result, if any 
X, Y, B, D - imchanged 
P - reflects the result, if any, else scrambled 

The vectors are defined as: 
Vector ffl ' DrawToois 3.0 - Draw 
Vector if2 - DrawToois 3.0 - Draw48 

Vector #3 - DrawToois 3.0 - DrawOn > 

Vector #4 - DrawToois 3.0 - Draw480n 

Vector ftS - DrawToois 3.0 - AnimatePixie (errors returned in A) 

Vector #6 - DrawToois 3.0 - Rnd 

Vector #7 - DrawToois 3.0 - Odds 

Vector #8 - DrawToois 3.1- Waitline 

Vector #9 - DrawToois 3. 1 - ErasePixie (errors retiimed in A) 

Vector #10 - DrawToois 3.1 - save intemipt space 

Vector #1 1 - DrawToois 3. 1 - restore interrupt space 

Vector ^^i2-#16 - reserved for ftiturexise 

Vectors 10 and 11 backup DrawToois' direct page space. This allows you to call most DrawToois' fimclions from a 
R\mQ task or another interrupt task. Alternately, you can use the scheduler. You will have to use these if an 
intemipt may occm during a DrawToois call; failure to do so may crash your program. 



Examples ; 
Parameters : 
Errors : 



For Merlin 16 : -GetQDT #MyQuickDispatchTable 

MyQDT (long) - location to save the copy of the quick dispatch table 

none 
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WorkCiirsor t ($4662^ 

Replaces tlie mouse cursor with the work cursor . Currently, the cursor is a pair of gears. 
Examples : WorkCursor (NumCalls) 

TOOLBOX(98, 70 : NumCails% ) 
Parameters ; NumCalls (word) - = animate on every StillWorking, n = every nth 

Errors : none 
t See WorkCursor2. 



WoritCursorZ f$6862) 

Same as WorkCusor, but works properly with accelaiator cards. 
Examples : WorkCursor2 (NumTicks) 

TOOLBOX( 98, 70 ; NumTicks % ) 
Parameters ; NumTicksIs (word) - = animate every StillWorking, n = every n/60ths sees. 

Errors : none 



StillVVorking (U762) 

WorkCursorAVorkCursor2 must be called first. Checks to see if the work cursor needs animating. Use InitCursor if 
you want to restore the cursor to an arrow. 
Examples : StillWorking; 

TOOLBOX(98,71) 
Parameters : none 
Errors ; none 



Odds ($4462^ 

Returns TRUE the given percentage of the time. Percentages of zero or less are always FALSE; percentages of 100 
or greater are always TRUE. This tool is accurate to about 2%. 
Examples: Boolean :=Odds(I^fcent); 

TOOLBOX( 98, 68 : 0, Percent%; Boolean% ) 
Parameters ; Boolean (word) - the truth value 

Percent (word) - the percentage of the time to be true. 
Errors : none 



RND (U562) 

Returns a pseudorandom number between I and the specified limit. Limits of zero or less always result in zero. 
Examples : number := RND( limit ); 

TOOLBOX( 98,69 ; 0, limit% ; number% ) 
Parameters : number (word) - the random number, i.., limit 

limit (word) - the maximum random number (1 ,,,32767) 
Errors : none 



NormalRND ($6562) 
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Rehims a normally-distributed, or "bell-curved", pseitdorandom number between 1 and the specified limit. The 
numbers are more likely to come from the center of the range than from the low or high ends of it. 
Examples : number := NormalRND( limit ); 

TOOLBOX(98, 101: 0, limit; number) 
Parameters : number - the random number, I. ..limit 

limit - the maximum random number (1... 32767) 
Errors : none 



HLoHd (S2F62) 

Handle LOAD. Loads a specified file into memory and returns a handle to it. (For those who like avoiding ail those 
GS/OS details, like me.) The handle is left locked. 
Examples : DataHandle := HLoad( Path, FileType ); 

TOOLBOX( 98, 47 : 0, 0, PathH%, PathL%, FileType%; DataL%, DafaH% ) 
Parameters : Path (lougword) - pointer to the GS/OS pathname 

FileType (word) - file type expected (or for any type) 

DataHandle (long) - handle to the file data 
Errors : GS/OS and memory manager errors (file busy errors handled internally) 

$620B - FileType mismatch 



HSave ($5462) 

Handle SAVE. Saves the contents of a handle in a file. If a new file is created, the file type is the same as the 
FileType parameter, and the AuxType is 0. The handle is left locked. 
Examples : HSave{ Path, FileType, DataHandle ); 

TOOLBOX( 98, 84 : PathH%, PaEhL%, FileType%, DataH%, DataL% ) 
Parameters : Path (longword) - pointer to the pathname 

FileType (word) - file type expected (or for any type) 

* type - 1 is a special type: PNT/$OOOI, packed screen (used with SetBackground) 

DataHandle (long) - handle to the data to be saved 
Errors : GS/OS and memory manager errors (file busy errors handled internally) 

$620B - FileType mismatch > 



BarGraph f$4B62) 

Draws a bar graph in a specified rectangle. The graph shows the percentage relationship between the "value" 
parameter and the max value in the graph record; values < 0% are treated as 0%; values >100% are treated as 100%, 
If the rectangle is larger vertically, the graph is drawn upward; if the rectangle is larger horizontally, it is drawn 
rightward. 

Examples ; BarGrapL( GraphRec, value ); 

TOOLBOX( 98, 75 ; GraphRecH%, GraphRecL%, value% ) 
Parameters : GraphRec (long) - pointer to a graph record 

GratA record ; 

0-7 Graph rectangle containing the graph 

8 ,9 ForeCol S olidPenPat value (- 1 for current pen pat) 

A,B BackCol SoIidBackPat value (- 1 for current back pat) 

C,D Max maximum value for the graph 

E-11 resa^fed reserved; set to 
Errors : none 



DrawTools3.1 



59 



GetMIIz m261) 

Returns the current GS speed to the nearest MHz. (Also adjusts GetJoy so that it wifl operate properly at the current 
speed.) 

Examples: Speed ;= GetMHz; 

TOOLBOX(98, 103 : 0; Speed%) 
Parameters: ■ Speed (uiteger) - speed of the GS to the nearest MHz. 
Errors: none 

PrintWindow f$6A62) 

Sends a window, grafport or the screen to the printer, Tlie Print Manager is automatically started, if necessary. No 
clipping is performed on overlapping windows. Also, you will need at least 32K free: PrintWindow .saves the 
contents of the screen before showing the dialogs. 
Examples: PrintWindow( WindowPtr, Options ); 

TOOLBOX(98, 106: WindowPtrH%, WmdowPtrL%, Options%) 
Parameten;: WindowPtr (long) - pointer to the window or grafport; if nil, prints whole screen 

Options (integer) 

bit - if 1, shows the "Page Setup" dialog box 
bit 1 - if 1, shows the "Print" dialog box 
bit 2-15 - reserved; set to 
Errors: Print Manager errors 

Memory Manager errors 
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Appendix A: DrawTools' Error Summary 



Hex 


Dec 


Meaning 


$0000 





NoOTOf 


$6201 


25089 


Too many libraries 


$6202 


25090 


Sequence number out of range 


$6203 


25091 


Invalid library ID 


$6204 


25092 


The library is loaded 


$6205 


25093 


Task signature missing/invalid 


$6206 


25094 


Screen Une out of range 


$6207 


25095 


Task exists (or doesn't exist, depending on tool) 


$6208 


25096 


SCB tasks are not enabled 


$6209 


25097 


Library buffer tables full (currently, maximum 5 buffers, for 45K) 


$620A 


25098 


Not enough memory in bank for more buffers 


$620B 


25099 


FileType Mismatch during a HLoad/HSave 


$620C 


25100 


Sequ^ce command mismatch (wrong command for this kind of pixie) 


$620D 


25101 


Undefined sequence command in this version of DrawTools 


$620E 


25102 


Pixie exists (or doesn't exist, depending on tool) 


$620F 


25103 


Play a'/Device number out of range 


$6210 


25104 


Game or Network Device not found 


$6211 


25105 


Not a matted pixie 


$62FF 


25343 


General etrot (consult tool descripticm) 



- not implemented (ie. for Apple's two reserved tool numbers, #7 and #8) 



( 
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Appendix B: Direct Page Usage 



DP AHHr 




Description 






Current drawing position, minus $2000 


d S 

H^J 


ii/\oE,_Ur 


Picture location in bank 




rOftrir 


Used by DrawMain & DrawShadow, thecurrait gra^rt 


A-Fl 




Ptr to QuickDraw II's pointer to the current grafport 


B.F 

E r 




Application's Memory ID, aux, type 15 






Scratclipad space for DrawTools 




Line 1 able 


Ptr to QuickDraw U s Ime table 


ZO*JJ 




Used by fading and colour tools (don't modify) 






Used by 5CB Intemipt nandler (don t modify) 




ouuriro 


Bits set 11 lire l>uttons are neld, %u.. 004321 




rUciVlHSK 


jjits true It nre button exists, $0..00432I 




r IX Alloc 


oit / - pixie allocated, bit 6 - pixie disabled 




r ix 1 ype 


pixie types 


66-75 


PixVsMat 


vi\ f piAic viaiuic, uii u " pi Ale IllnUtxl 


76-7B 




Scratchpad space for Animatioa tools 


7C-7D 


FontCode 


XOR of current font handle words 


7E-81 


GrafPort* 


Ptr to pnloc field in current grafiport 


82-83 


FontHeight 


Current font height 


84-85 


LeftMargin 


Lefttnargin 


86-87 


RighEMargin 


Right margin 


88-89 


UtilTemp 


Used for derefenajcing 


8A-8B 


CurrentLib 


Library ID for the current library 


8C-FF 




Misc. or future use (don't raodi^) 



You may use any of the scratchpad space between DrawTools calls. 
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Appendix C: DrawTools and Other Toolsets 

DrawTools should be compatible with all of the standard Apple toolsets. However, the follcwijig are a few things to 
notice. 

1 . DrawTools and ESP/FT A's SoundTools (TOOL^IQ) 

You cannot use the SCB Interrupt tools with the Soundtrack Tools. 

2. Bit-mapped Graphics and OuickPraw T| 

a) Coordinates - DrawTools' coordinate system is identical to QuickDraw's 320 mode (0.,.319, 0...199). However, 
the coordinates are always global. Use the QuickDraw function LocfllToGlobal when you are usmg 
windows/gra^rts to determine the proper coordinates. 

b) 640 mode - DrawTools drawing functions will work as you'd expect, creatmg 48x24 pictures instead of 24x24 
pictures. The coordinates are always 0...319, 0...199, even if you are using QuickDraw in 640 mode. To determine 
the proper coordmatts in a window/grafport, use the following (in Pascal): LocalToGIobal( WindowPoint ); 
WindowPoint,h := WindowPoint Ji div 2; 

DtswwhatewrAti WindowPoint.h, WindowPomt.v, picture_number ); 

c) Mouse Cursor - The drawing fimctions and screen scrolling functions opiate directly on the screen, ignoring 
the mouse cursor. If you need a cursor on the screen, use HideCursor/ShowCursor. 

d) Clipping - For speed, the drawing functions don't clip pictures to fit in the clipping regions of the current 
grafjwrt (if you draw a picture, the entire picture is always drawn, even if it won't fit in a window). 

3. Memory Manager 

DrawTools uses auxID iS'15. When you shut down DrawTools, all memory allocated with aux ID #15 is disposed of 
(includmg any HLoaded handles). 
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Appendix D: Network and Game Drivers 



What are Network and Game Drivers? 

DrawTools lets you assign devices for up to four players. You can specify a device number when you call 
GetFire, StillFiring or GetJoy. Device is always the GS joystick, but device 1 to 4 can be assigned to any device. 
By following the standards set in this addendum, your game (or other application) will be able to play with any 
device, allowing for even players on other OS's. All this is possible by what I call a game driver. 

A driver in OS/OS is a piece of software that runs an input/output device, like a printer or a disk drive. A game 
driver is a piece of software that DrawTools uses to run an input device, typicaliy for a game (hence the name). 
Game drivers are kept in a folder called DT.Drivers, located in the Tools folder on a boot disk. All your 
application has to do is use SFGetPile (the standard Open... dialog) to let the players select their drivers from that 
directory. You load them with the System Loader and tell DrawTools which game driver to use for which player, and 
the rest is done automatically. 

If you want to go all the way and let players play on separate GS's, you'll need a net driver as well. Hiis is a 
piece of software that DrawTools uses to communicate between separate computes, such as over a modem or an 
AppleTalk network. Using a net driver is a little more coaq)licated than using game drivers alone, although 
DrawTools does a lot coordinating behind the scenes for you. You have to use a special tool called SendNetwork 
to send messages between the different GS's your program is running on. SendNetwork also returns to you status 
information about the other GS's, such as when a new player has started his computer and wants to join in, or when 
one of the existing players loses or wants to quit. Reading a player's device on anothw GS is done the same way as 
you would normally do, with GetJoy or the other joystick routines. If the player is not on your GS, DrawTools asks 
the Net Driver to find out the information for you. 



Your Application 




i 

DrawTools 




1 1 

Game Driver Net Driver 




1— 




Apple IIGS#1 



-Network — 



Your Application 

1 

DrawTools 



Net Driver Game Driver 



Apple IIGS #2 



Figure 1 - How the Game and Net Drivers work together 



I hope that by explaining the details here, that all the people that have more time than I do will get to work and 
start making game and net drivers. I set up the rules; somebody else makes the drivers. If you come up with a net or 
game driver, please send me a copy and a letter, and I'll try to market them with future disks. If you just want to use 
the net and game drivers, read on to find how how to set up your programs to support them. Located on the latest 
DrawTools' Disks is a folder called DT.Drivers, which you can copy into the Tools fold« of your boot disk 
containing DrawTools. First, there is a sample game driver called Joystick that nms the GS Joystick. Second, 
there is a 5aiiq}ie net driver called Null.NetDriver which mimics the some functions of a real net driver. (130 & 
13 1 are special commands to mimic activities on a network for testing purposes - see SendNetwork in therefa^nce.) 
Source files for the Merlin assembler are included ia the folde*. You can use these to test your program if you want 
to support game drivers, or net drivm and game drives. As I mentioned previously, thwe is no reason "game" 
drivers have to be used in games. You might find it easier to write a game drivw to opwate a device like a flying 
mouse (the headset mouse used for the handicapped) than to write some kind of GS/OS driver (or whatever), and once 
written, such a driver can be iised in any program supporting game drivers. The possibilities are mormous. 



A Few Definitions; 
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A device is something used by a person to offer input to an application, sucli as a keylx)ard, joystick. Koala pad, or 
a microphone. 

A local device is a device connected directly to a IIGS. 

A remote device is a device connected indirectly to a lIGS, by an AppleTalk network, or a modem, or a SCSI port to 
another IIGS. 

A Game Driver is a piece of software which operates or monitors a local device. 

A Net Driver is a piece of software which is used by DrawTooIs to communicate over a network with remote 
devices. 

What Does My Application Have To Do To Support Game Drivers? 
What the Application does ... 

1. You will have to load the game drivers desired by the players (Hsing LoadDriver) into memory. The drivers 
should be located in theDT.Drlvers folder in the Tools directory of the boot disk, 

2. Use SetGameDriver (playerNum, DriverPtr) to install a driva- for a particular person. One driver may be shared by 
more than one person (unless, of course, it's strictly a one person device, like a joystick — it's up to the players to 
chose devices that make sense). 

3. When you use GetJoy, GetFire, or StillFiring, use the playerNum to specify a particular device. 

4. Unload the driver when you are done. 

What DrawTools does ... 

DrawTools will invoke the appropriate game driver instead of reading the GS joystick. If no driver exists, garbage is 
returned by the call. 

What the Game Driyer does ... 

The game driver reads the local device and returns the information requested to DravvTooIs, which hands it to your 
application, 

What Does My Application Have To Do To Use Net Drivers? 

What the Application does ... 

1 . Load the appropriate net driver into memory. 

2. Use SetNetI>river( driv^Ptr ) to install the net driver. The current version of DrawTools only supports one net 
driver; you can't play over two different networks at the same time. 

3. When a player on a local device wants to start playing, use SeodNetworic to inform the othCT GS (or GS's) that 
there is a new player. A message is returned if the GS's are f\ill (DrawTools only supports 4 players at a time, even 
over a network). 

4. Periodically invoke SendNetwork (eg, by placing it in your main loop) to let the net driver check on the network 
and keep up-to-date with the other GS (or GS's). This is called polling the network. If there are new players jumpmg 
into the game, or old players droppmg out, SendNetwork will return the appropriate message. More details on the 
uses of SendNetwork are listed in the refereoce. 

What DrawTools Does ... 

If you use GetFire, GetJoy or StillFiring for a playw on a remote device, DrawTools invokes the Net Driver and 
asks it to find the information, which it returns to yoiu' application. 

What the Net Driver Does ,.. 

The driver must handle the transmission and reception of data over the network. It takes care of identifying which 
player number on the local GS corresponds to which device on which remote GS. When a new player enters the 
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network, the net driver finds a free player number aad reports it to your application for use with GetJoy, etc. 
How to Create a Game Driver 

1. File description: your driver must be stored in DT.Drivers folder in Tools folder of the boot disk. FileType: 
Generic Load File (type $BC) AuxType I. 

2, Header for you driver; 



Offset EJa^ Si^ Desa-ipticm 

Entry Pt (3 bytes) BRLinstniction to your driver 

3 Name (17 bytes) Pascal string for the driver name 

20 Creator (17 bytes) Your name or the name of your company 

37 Version (word) Driver version (eg, $101 = 1.1) 

39 DTVersion (wotd) Minimum version of DrawTools (eg. $301 =3.1) 

41 <reserved> (8 bytes) Zctocs 

49 ... <yoHr driver goes here> 



DrawTools will call your driver with a JSL to the entry point. A = comiuand, X = player #, Y = result of the 
command. 

B & D registers must (naturally) be preserved. Place the result in A. Exit with a SEC and RTL, 

The commands for game drivers are: - init driver (called by SetGameDriver, return error code ($6210 or other) or 

else 0) 1- GetJoy (Y=axis, called by GetJoy) 2 - GetFire (called by GetFire) 3 - StillFiring (called by StillFiring) 

How to Create a Net Driver 

1, File description : must be stored in DT.Drivers folder in Tools folder of the boot disk. FileType: Generic Load File 
(type $BC) AuxType 2. 

2. HeadCT for you driver: 





Name 


Size 


De?<?riptipn 





BntryPt 


(3 bytes) 


BRL instruction to your driver 


3 


Name 


(17 bytes) 


Pascal string for the driver name ' 


20 


Creator 


(17 bytes) 


Your nanie or the name of your company 


37 


Version 


(woid) 


Driver version (eg. $100 = 1.00) 


39 


DTVersion 


(wofd) 


Minimum version of DrawTools (eg $301 = 3.1) 


41 


<reserved> 


(8 bytes) 


Set to 


49 






<your driver goes hero 



DrawTools will call your driver with a JSL to the entry point. A is the command, X = data (low), Y = data (high). 
B & D registers must be preserved. Return with the result in A, and any data in X,Y, Exit with an RTL. 
For the commands, see the reference under SendNetwork. You will need a pseudo game driver for DrawTools to call 
when it wants information for a local device. For your game driver, design it to be called like a regular game driver, 
except return with a CLC (not SEC) and RTL. This will make sure DrawTools won't s^id the results of the 
GetJoy/etc. back to you (posting local events). 
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Appendix E : Usin^ PicEd 3.0 

Besid&s the library converter utility, there is a utility called PicEd that helps you to create libraries of the 
bit-mapped pictures that DrawTools' works with. PicEd was written in TML Pascal II, vl.l. 

When PicEd is started, th»e is a large grid of 24x24 black blocks to the right of the screen. This is a zoom 
(fat pixels) view of the current picture. Using the mouse, you can change the blocks to different colours. While you 
are editmg a picture, the changes you make are TEMPORARY until you select the EDIT button. This way, if you 
make a mistake, you can always revert to the origmal copy of the picture and start again. 

When blocks in the zoom view are changed, these changes are reflected on a series of pictures in the top-left 
comer of the screen. The large picture is a view of how the picture would look if it were drawn with the Draw48 
call. To the left of this picture are three smaller ones. The one on the far left is drawn with Draw, The one in the 
middle is drawn with DrawOn (that is, matted) on a red background. TTie one on the right is used when animating. 

There is a palette of colours to the left of the zoom view. You can change the colour you are sketching 
with by clicking on a new colour. The new colour is outlined in black. 

Below the palette is a series of buttons; 
QUIT - this stops PicEd. It gives no warnings, so make sure your work is saved, 
cm - clears the zoom view to black, 

EDIT - saves the current picture in the library, and selects anotho- for editing 

When EDIT is first clicked, PicEd gives you three options: (S)am6 - save the current picture to library position it 
was edited fi^om; (D)ont - don't save the ciurent picture in the library; (N)ew - save the current picture to a new 
position. If you pick new, you will be asked for a new position (0...31). 
LOAD - loads a library of pictures from disk. 

SAVE - saves a library of pictures to disk. Pressing Return will use the LOAD name as the default. 

MASK - calls GeoMask to create a simple matting mask. Normally, this mask is stored immediately after the 

picture it was created for. I 

The PAL and AMI buttons are special buttons which cause a new set of buttons to appear on the screen. 
The PAL (palette) buttons are: 

PAL - let's you select one of 16 palettes to use, palette being the default palette of colours used by QuickDraw. If 

you change any of the palettes (besides palette 0), the information is saved in the file PicEd.dat, and the palettes will 

be reloaded the next time you run PicEd, Some of the palettes are predefined as the 640 colours, the standard IBM 

VGA colours, metallic and rainbow colours. ^ 

COL - change a colour in the current palette. 

FADE - brightens or dims a colour by using the FadeColour tool, 

BLND - blends two colours together to produce a third by calling the BlendColour tool. 

The AN I (Animation) buttons as as follows: 
DONE - you are finished animation. Gets you out of animation mode and restores the other buttons. 
SEQ - defme an animation sequence. If you want to animate a set of pictures in the current library, select this 
button, then type in each picture you want to animate, in order. Then type 255 and type in the position in the 
sequMice you want to loop back to (ie. = first position, 1 = second, etc). To animate the first 3 pictures over and 
over, you'd type: then 1 then 2 then 255 then 0. 

GOl - animates the sequence you typed in. Hold down the mouse to stop. From left to right, the pictures are drawn: 
1) as a matted pixie on a red background, 2) as a pixie that is not maUed, 3) as a 48x48 picture (by Draw48). 
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Appendix F : Using Library Converter 1.2 

Lib.Converter, tlie library converter, is a utility that lets you translate a picture library template into a DrawTools 
picture li[)rary. A template is simply a super hi-resolution screen with the 32 pictures of a pictiu-e library laid out 
for you to edit with any paint program, Keep in mind that the template must be saved as a super lii-resoiution 
screen and not as one of the other picture tbrmats, such as Apple Preferred. 

Convert Template to Library ... (Conimand-Oo): Select this to convert a template to a picture library. 
Lib.Converter will ask you which template you would like to convert. During the conversion, the template pictures 
are displayed on the desktop. Once the template is converted, Lib.Converter will ask you what name you would like 
to .save the picture library as. 

Display a Template ... (Command-Dd); Select this to display the pictures in a template on the screen, Tlie colours 
may differ from the original template. 

Print a Template ... (Command-Pp): Select this to print a template to the printer. Lib.Converter uses PrintWindow 
to print the entire screen (including the pictures). 

Convert SHR Screen to SetBack ... (Conimand-Bb): Select this to convert a super hi-resolution screen to a packed 
super hi-resolution screen, the format used by SetBackground and SetBackground2. 

Pack (Command-Pp): When Pack is checkmarked, the template you convert with "Convert Template to Library" will 
be packed, 
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Appeadix G : Changes Since DrawTools 3.0 

1. New ORCA/M macros. 

2. CLS now works with a visible cursor. 

3. NorinalRND no longer retiims a uniform distribution. 

4. NEW WorkCursor2: WorkCursor that works with accelerator cards. 

5. New QDT Vectors: 

#8 -> WaitLiiie ff9 -> ErasePixie 

#10 -> Save intemipE space #1 1 -> Restore interrupt space 

6. HLoad waits luitil a file is not busy. 

7. HLoad now works with files larger than 64K. 

8. Change status command for fine pixies now works. 

9. The library limit has been increased to 24 from 16, 

10. Library Converter has been updated to version 1,1, Requires System 6,0. 
1 i. SetGameDriver no longer crashes and it returns error $62FF properly. 

12. NEW ErasePixie: A more convenient form of WipeOn. 

13. NEW EraseAUPixies. 

14. NEW LoadDriver: Loads a game or net driver. 

15. NEWUnloadDriver. 

16. BarGraph supports 16 colours for the forecolour, if you are using System 6.0. 

17. SetNetDfiver returns error $62FF properly. 

18. NEW SetBackground2; SetBackground with more options. 

19. NEW Keypad.I>rvr & Keybwl.EJrw: game drivers for the Apple TIGS keyboard, 

20. NEW ResetBuffers: Clears the bank drawing buffers, 

21. NEW PrintWindow: Print the contents of a window or the screen. 

22. New self-nmning Micol Advanced BASIC demo, 

23. WaitLine is now more accurate: interrupts are suspended to ensure prompt response. (This was the 
problem that made Quest for the HoardTw sluggish when many inits were installed.) 
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Tool Index (in alphabetical order') 



Animate 
AnimatePixie 

BaiGiaph 
BleadColoiir 

ClearPixie 

ClrSCBInts 

Cls 

DelSCBInt 

DisaWePixie 

Draw 

Draw48 

DrawAt 

Driw480ii 

Draw48At 

Draw480iiAt 

DrawBootlnit 

DrawNornial 

DrawOn 

E)rawOnAt 

DrawPage 

DrawPos 

DrawReset 

DrawShadow 

DrawSrartUp 

E>rawStatus 

DrawShutDown 

DrawVerston 

EnablePixie 

EiiableSCBInts 

ErasePixie 

EraseAllPixies 

ExteadBuffers 

FadeColour 

FadeDone 

FadePal 

FmdColour 

FindPalette 

GetBwda 

GenMask 

GenAllMasks 

GetFire 

GetJoy 

GetMHz 

Getlibrary 



40 
40 

58 
48 

39 
50 
42 

49 
40 
34 
34 
34 
34 
34 
35 
30 
33 
34 
35 
32 
32 
31 
33 
30 
3! 
30 
30 

40 
49 
41 
41 
32 

48 
49 
46 
47 
48 

44 
35 
35 
55 
55 
58 
37 



GetPalette 
GetPixie 
GetPixieSeq 
GetQDT 

HidePixie 

HLoad 

Home 

HSave 

HTab 

IncrFadeOut/In 

LoadDriver 
Loadlibraiy 

NewPixie 
NormalRND 

Odds 

Print 
PrintHex 
Printlnt 
PrintWindow 

QuickFadeOut/In 
QiiickWipe 

Ready2Priiit 
ResetBuffers 
ResetSCBs 
.ResumeSCBInts 
R^fD 

ScrollLinesL 

ScrollLinesR 

ScrollLinesU 

ScrollLinesD 

SendNetwoik 

SetBackgfoiind 

SetBackgrDund2 

Set Border 

SetColoiir 

SetColPercent 

SetDrawPage 

SetDrawPos 

SetGameDriver 

Setlibrary 

SetLTMargins 

SetNetDrivo- 



46 
39 
39 
56 

40 
58 
51 
58 
51 

43 

53 
37 

38 
57 

57 

52 
52 
52 
59 

42 
42 

51 
32 
44 
50 
57 

45 
45 
45 
45 
53 
36 
36 
44 
47 
47 
33 
32 
53 
37 
51 
53 
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SetPalette 46 

SetPixie 39 

SetPixieSeq 39 

SetSCBIiit 49 

SetSCBs 44 

ShowPixie 40 

Sha£Io^vOff 43 

ShadowOn 43 

StillFiring 55 

SfiUWorking 57 

UnfiidePal 46 

UnloadDfiver 53 

Unloadlibrary 37 

VBWipe 42 

VTab 51 

WaitVB 43 

WaitLine 43 

WipeOn 36 

WorkCursof 57 

WorkCursor2 57 



